Various minor text tweaks.
[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;">Apache 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 this 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 to read 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 reading 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 a 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 to read 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 are 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 a 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> need 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 build your 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 used 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
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
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         Note that 0.40 of libmemcached is required.
706        </para>
707        </listitem>
708       </varlistentry>
709       <varlistentry>
710        <term>
711         <literal>--with-redis</literal>
712        </term>
713        <listitem>
714         <para>&yaz; will be linked with the hiredis C library
715         to allow for result-set caching for ZOOM on a
716         <ulink url="&url.redis;">redis</ulink> server.
717         The prefix can not be given. Note that YAZ will only search
718         for hiredis if Libgcrypt is also enabled.
719        </para>
720        </listitem>
721       </varlistentry>
722
723      </variablelist>
724     </para>
725     <para>
726      When configured, build the software by typing:
727      <screen>
728       make
729      </screen>
730     </para>
731     <para>
732      The following files are generated by the make process:
733      <variablelist>
734       <varlistentry>
735        <term><filename>src/libyaz.la</filename></term>
736        <listitem><para>
737         Main &yaz; library. This is no ordinary library. It's
738         a Libtool archive.
739         By default, &yaz; creates a static library in
740         <filename>lib/.libs/libyaz.a</filename>.
741        </para></listitem>
742       </varlistentry>
743       <varlistentry>
744        <term><filename>src/libyaz_server.la</filename></term>
745        <listitem><para>
746          Generic Frontend server. This is an add-on for libyaz.la.
747          Code in this library uses POSIX threads functions - if POSIX
748          threads are available on the platform.
749         </para></listitem>
750       </varlistentry>
751       <varlistentry>
752        <term><filename>src/libyaz_icu.la</filename></term>
753        <listitem><para>
754         Functions that wrap the ICU library.
755         </para></listitem>
756       </varlistentry>
757       <varlistentry>
758        <term><filename>ztest/yaz-ztest</filename></term>
759        <listitem><para>Test Z39.50 server.
760        </para></listitem>
761       </varlistentry>
762       <varlistentry>
763        <term><filename>client/yaz-client</filename></term>
764        <listitem><para>Z39.50 client for testing the protocol.
765        See chapter <link linkend="yaz-client">
766        YAZ client</link> for more information.
767        </para></listitem>
768       </varlistentry>
769       <varlistentry>
770        <term><filename>util/yaz-config</filename></term>
771        <listitem><para>A Bourne-shell script, generated by configure, that
772        specifies how external applications should compile - and link with
773        &yaz;.
774        </para></listitem>
775       </varlistentry>
776       <varlistentry>
777        <term><filename>util/yaz-asncomp</filename></term>
778        <listitem><para>The ASN.1 compiler for &yaz;. Requires the
779        Tcl Shell, <application>tclsh</application>, in
780        <literal>PATH</literal> to operate.
781        </para></listitem>
782       </varlistentry>
783       <varlistentry>
784        <term><filename>util/yaz-iconv</filename></term>
785        <listitem><para>This program converts data in one character set to
786        another. This command exercises the YAZ character set
787        conversion API.
788        </para></listitem>
789       </varlistentry>
790       <varlistentry>
791        <term><filename>util/yaz-marcdump</filename></term>
792        <listitem><para>This program parses ISO2709 encoded MARC records
793        and prints them in line-format or XML.
794        </para></listitem>
795       </varlistentry>
796       <varlistentry>
797        <term><filename>util/yaz-icu</filename></term>
798        <listitem><para>This program exposes the ICU wrapper library if that
799        is enabled for YAZ. Only if ICU is available this program is
800        useful.
801        </para></listitem>
802       </varlistentry>
803       <varlistentry>
804        <term><filename>util/yaz-url</filename></term>
805        <listitem><para>This program is a simple HTTP page fetcher ala
806        wget or curl.
807        </para></listitem>
808       </varlistentry>
809       <varlistentry>
810        <term><filename>zoom/zoomsh</filename></term>
811        <listitem><para>
812         A simple shell implemented on top of the
813         <link linkend="zoom">ZOOM</link> functions.
814         The shell is a command line application that allows you to enter
815         simple commands to perform ZOOM operations.
816        </para></listitem>
817       </varlistentry>
818       <varlistentry>
819        <term><filename>zoom/zoomtst1</filename>,
820        <filename>zoom/zoomtst2</filename>, ..</term>
821        <listitem><para>
822         Several small applications that demonstrates the ZOOM API.
823        </para></listitem>
824       </varlistentry>
825      </variablelist>
826     </para>
827     <para>
828      If you wish to install &yaz; in system directories
829      <filename>/usr/local/bin</filename>,
830      <filename>/usr/local/lib</filename> .. etc, you can type:
831     </para>
832     <screen>
833      make install
834     </screen>
835     <para>
836      You probably need to have root access in order to perform this.
837      You must specify the <literal>--prefix</literal> option for configure if
838      you wish to install &yaz; in other directories than the default
839      <filename>/usr/local/</filename>.
840     </para>
841     <para>
842      If you wish to perform an un-installation of &yaz;, use:
843     </para>
844     <screen>
845      make uninstall
846     </screen>
847     <para>
848      This will only work if you haven't reconfigured &yaz; (and therefore
849      changed installation prefix). Note that uninstall will not
850      remove directories created by make install, e.g.
851      <filename>/usr/local/include/yaz</filename>.
852     </para>
853    </sect2>
854    <sect2 id="installation-linking-yaz-unix">
855     <title>How to make apps using YAZ on UNIX</title>
856     <para>
857      This section describes how to compile - and link your own
858      applications using the &yaz; toolkit.
859      If you're used to Makefiles this shouldn't be hard. As for
860      other libraries you have used before, you need to set a proper include
861      path for your C/C++ compiler and specify the location of
862      &yaz; libraries. You can do it by hand, but generally we suggest
863      you use the <filename>yaz-config</filename> that is generated
864      by <filename>configure</filename>. This is especially
865      important if you're using the threaded version of &yaz; which
866      require you to pass more options to your linker/compiler.
867     </para>
868     <para>
869      The <filename>yaz-config</filename> script accepts command line
870      options that makes the <filename>yaz-config</filename> script print
871      options that you should use in your make process.
872      The most important ones are:
873      <literal>--cflags</literal>, <literal>--libs</literal>
874      which prints C compiler flags, and linker flags respectively.
875     </para>
876     <para>
877      A small and complete <literal>Makefile</literal> for a C
878      application consisting of one source file,
879      <filename>myprog.c</filename>, may look like this:
880      <screen>
881       YAZCONFIG=/usr/local/bin/yaz-config
882       CFLAGS=`$(YAZCONFIG) --cflags`
883       LIBS=`$(YAZCONFIG) --libs`
884       myprog: myprog.o
885          $(CC) $(CFLAGS) -o myprog myprog.o $(LIBS)
886       </screen>
887     </para>
888     <para>
889      The CFLAGS variable consists of a C compiler directive that will set
890      the include path to the <emphasis>parent</emphasis> directory
891      of <filename>yaz</filename>. That is, if &yaz; header files were
892      installed in <filename>/usr/local/include/yaz</filename>,
893      then include path is set to <filename>/usr/local/include</filename>.
894      Therefore, in your applications you should use
895      <screen>
896       #include &lt;yaz/proto.h>
897      </screen>
898      and <emphasis>not</emphasis>
899      <screen>
900       #include &lt;proto.h>
901      </screen>
902     </para>
903     <para>
904      For Libtool users, the <filename>yaz-config</filename> script provides
905      a different variant of option <literal>--libs</literal>, called
906      <literal>--lalibs</literal> that returns the name of the
907      Libtool archive(s) for &yaz; rather than the ordinary ones.
908     </para>
909     <para>
910      For applications using the threaded version of &yaz;,
911      specify <literal>threads</literal> after the
912      other options. When <literal>threads</literal> is given,
913      more flags and linker flags will be printed by
914      <filename>yaz-config</filename>. If our previous example was
915       using threads, you'd have to modify the lines that set
916      <literal>CFLAGS</literal> and <literal>LIBS</literal> as
917      follows:
918      <screen>
919       CFLAGS=`$(YAZCONFIG) --cflags threads`
920       LIBS=`$(YAZCONFIG) --libs threads`
921      </screen>
922      There is no need specify POSIX thread libraries in your Makefile.
923      The <literal>LIBS</literal> variable includes that as well.
924     </para>
925    </sect2>
926   </sect1>
927   <sect1 id="installation.win32">
928    <title>Windows</title>
929    <para>The easiest way to install YAZ on Windows is by downloading
930    an installer from
931    <ulink url="&url.yaz.download.win32;">here</ulink>.
932    The installer comes with source too - in case you wish to
933    compile YAZ with different compiler options, etc.
934    </para>
935
936    <sect2 id="installation.win32.source">
937     <title>Compiling from Source on Windows</title>
938     <para>
939      &yaz; is shipped with "makefiles" for the NMAKE tool that comes
940      with <ulink url="&url.vstudio;">
941      Microsoft Visual Studio</ulink>. It has been tested with
942      Microsoft Visual Studio 2013.
943     </para>
944     <para>
945      Start a command prompt and switch the sub directory
946      <filename>WIN</filename> where the file <filename>makefile</filename>
947      is located. Customize the installation by editing the
948      <filename>makefile</filename> file (for example by using notepad).
949      The following summarizes the most important settings in that file:
950      <variablelist>
951       <varlistentry>
952        <term><literal>DEBUG</literal></term>
953        <listitem><para>
954         If set to 1, the software is
955         compiled with debugging libraries (code generation is
956         multi-threaded debug DLL).
957         If set to 0, the software is compiled with release libraries
958         (code generation is multi-threaded DLL).
959        </para></listitem>
960       </varlistentry>
961       <varlistentry>
962        <term><literal>HAVE_TCL</literal>, <literal>TCL</literal></term>
963        <listitem><para>
964         If <literal>HAVE_TCL</literal> is set to 1, nmake will
965         use the ASN.1 compiler (<ulink url="&url.tcl;">Tcl</ulink> based).
966         You must set <literal>TCL</literal> to the full path of the Tcl
967         interpreter. A Windows version of Tcl is part of
968         <ulink url="&url.gitwindows;">Git for Windows</ulink>.
969        </para>
970        <para>
971         If you do not have Tcl installed, set
972         <literal>HAVE_TCL</literal> to 0.
973        </para></listitem>
974       </varlistentry>
975       <varlistentry>
976        <term><literal>HAVE_BISON</literal>,
977        <literal>BISON</literal></term>
978        <listitem><para>
979         If GNU Bison is present, you might set <literal>HAVE_BISON</literal>
980         to 1 and specify the Bison executable in <literal>BISON</literal>.
981         Bison is only required if you use the Git version of
982         YAZ or if you modify the grammar for CQL
983         (<filename>cql.y</filename>).
984        </para>
985        <para>
986         A Windows version of GNU Bison is part of
987         <ulink url="&url.gitwindows;">Git for Windows</ulink>.
988        </para></listitem>
989       </varlistentry>
990       <varlistentry>
991        <term><literal>HAVE_ICONV</literal>,
992        <literal>ICONV_DIR</literal></term>
993        <listitem><para>
994         If <literal>HAVE_ICONV</literal> is set to 1, YAZ is compiled
995         with iconv support. In this configuration, set
996         <literal>ICONV_DIR</literal> to the iconv source directory.
997        </para></listitem>
998       </varlistentry>
999       <varlistentry>
1000        <term><literal>HAVE_LIBXML2</literal>,
1001        <literal>LIBXML2_DIR</literal></term>
1002        <listitem>
1003         <para>
1004          If <literal>HAVE_LIBXML2</literal> is set to 1, YAZ is compiled
1005          with SRU support. In this configuration, set
1006          <literal>LIBXML2_DIR</literal> to the
1007          <ulink url="&url.libxml2;">libxml2</ulink> source directory.
1008         </para>
1009         <para>
1010          You can get pre-compiled Libxml2+Libxslt DLLs and headers from
1011          <ulink url="&url.libxml2.download.windows;">here</ulink>.
1012          Should you with to compile those libraries yourself, refer to
1013          to <xref linkend="installation.windows.libxml2"/>
1014         </para>
1015        </listitem>
1016       </varlistentry>
1017       <varlistentry>
1018        <term><literal>HAVE_LIBXSLT</literal>,
1019        <literal>LIBXSLT_DIR</literal></term>
1020        <listitem>
1021         <para>
1022          If <literal>HAVE_LIBXSLT</literal> is set to 1, YAZ is compiled
1023          with XSLT support. In this configuration, set
1024          <literal>LIBXSLT_DIR</literal> to the
1025          <ulink url="&url.libxslt;">libxslt</ulink> source directory.
1026         </para>
1027         <note>
1028          <para>
1029           libxslt depends on libxml2.
1030          </para>
1031         </note>
1032        </listitem>
1033       </varlistentry>
1034       <varlistentry>
1035        <term><literal>HAVE_ICU</literal>,
1036        <literal>ICU_DIR</literal></term>
1037        <listitem>
1038         <para>
1039          If <literal>HAVE_ICU</literal> is set to 1, YAZ is compiled
1040          with <ulink url="&url.icu;">ICU</ulink> support.
1041          In this configuration, set
1042          <literal>ICU_DIR</literal> to the
1043          <ulink url="&url.icu;">ICU</ulink> source directory.
1044         </para>
1045        </listitem>
1046       </varlistentry>
1047      </variablelist>
1048     </para>
1049     <para>
1050      When satisfied with the settings in the makefile, type
1051      <screen>
1052       nmake
1053      </screen>
1054     </para>
1055     <note>
1056      <para>
1057       If the <filename>nmake</filename> command is not found on your system
1058       you probably haven't defined the environment variables required to
1059       use that tool. To fix that, find and run the batch file
1060       <filename>vcvars32.bat</filename>. You need to run it from within
1061       the command prompt or set the environment variables "globally";
1062       otherwise it doesn't work.
1063      </para>
1064     </note>
1065     <para>
1066      If you wish to recompile &yaz; - for example if you modify
1067      settings in the <filename>makefile</filename> you can delete
1068      object files, etc by running.
1069      <screen>
1070       nmake clean
1071      </screen>
1072     </para>
1073     <para>
1074      The following files are generated upon successful compilation:
1075      <variablelist>
1076       <varlistentry>
1077        <term><filename>bin/yaz&soversion;.dll</filename> /
1078        <filename>bin/yaz&soversion;d.dll</filename></term>
1079        <listitem><para>
1080         &yaz; Release/Debug DLL.
1081        </para></listitem>
1082       </varlistentry>
1083       <varlistentry>
1084        <term><filename>lib/yaz&soversion;.lib</filename> /
1085        <filename>lib/yaz&soversion;d.lib</filename></term>
1086        <listitem><para>
1087         Import library for <filename>yaz&soversion;.dll</filename> /
1088         <filename>yaz&soversion;d.dll</filename>.
1089       </para></listitem>
1090       </varlistentry>
1091       <varlistentry>
1092        <term><filename>bin/yaz_cond&soversion;.dll</filename> /
1093        <filename>bin/yaz_cond&soversion;d.dll</filename></term>
1094        <listitem><para>
1095         Release/Debug DLL for condition variable utilities (condvar.c).
1096        </para></listitem>
1097       </varlistentry>
1098       <varlistentry>
1099        <term><filename>lib/yaz_cond&soversion;.lib</filename> /
1100        <filename>lib/yaz_cond&soversion;d.lib</filename></term>
1101        <listitem><para>
1102         Import library for <filename>yaz_cond&soversion;.dll</filename> /
1103         <filename>yaz_cond&soversion;d.dll</filename>.
1104        </para></listitem>
1105       </varlistentry>
1106       <varlistentry>
1107        <term><filename>bin/yaz_icu&soversion;.dll</filename> /
1108        <filename>bin/yaz_icu&soversion;d.dll</filename></term>
1109        <listitem><para>
1110         Release/Debug DLL for the ICU wrapper utility.
1111         Only build if HAVE_ICU is 1.
1112        </para></listitem>
1113       </varlistentry>
1114       <varlistentry>
1115        <term><filename>lib/yaz_icu&soversion;.lib</filename> /
1116        <filename>lib/yaz_icu&soversion;d.lib</filename></term>
1117        <listitem><para>
1118         Import library for <filename>yaz_icu&soversion;.dll</filename> /
1119         <filename>yaz_icu&soversion;d.dll</filename>.
1120        </para></listitem>
1121       </varlistentry>
1122       <varlistentry>
1123        <term><filename>bin/yaz-ztest.exe</filename></term>
1124        <listitem><para>
1125         Z39.50 multi-threaded test/example server. It's a WIN32
1126         console application.
1127       </para></listitem>
1128       </varlistentry>
1129       <varlistentry>
1130        <term><filename>bin/yaz-client.exe</filename></term>
1131        <listitem><para>
1132         &yaz; Z39.50 client application. It's a WIN32 console application.
1133         See chapter <link linkend="yaz-client">YAZ client</link> for more
1134         information.
1135       </para></listitem>
1136       </varlistentry>
1137       <varlistentry>
1138        <term><filename>bin/yaz-icu.exe</filename></term>
1139        <listitem><para>This program exposes the ICU wrapper library if that
1140        is enabled for YAZ. Only if ICU is available this program is
1141        built.
1142       </para></listitem>
1143       </varlistentry>
1144       <varlistentry>
1145        <term><filename>bin/zoomsh.exe</filename></term>
1146        <listitem><para>
1147         Simple console application implemented on top of the
1148         <link linkend="zoom">ZOOM</link> functions.
1149         The application is a command line shell that allows you to enter
1150         simple commands to perform ZOOM operations.
1151       </para></listitem>
1152       </varlistentry>
1153       <varlistentry>
1154        <term><filename>bin/zoomtst1.exe</filename>,
1155        <filename>bin/zoomtst2.exe</filename>, ..</term>
1156        <listitem><para>
1157         Several small applications that demonstrate the ZOOM API.
1158       </para></listitem>
1159       </varlistentry>
1160      </variablelist>
1161     </para>
1162    </sect2>
1163
1164    <sect2 id="installation-linking-yaz-win32">
1165     <title>How to make apps using YAZ on Windows</title>
1166     <para>
1167      This section will go though the process of linking your Windows
1168      applications with &yaz;.
1169     </para>
1170     <para>
1171      Some people are confused by the fact that we use the nmake
1172      tool to build &yaz;. They think they have to do that too - in order
1173      to make their Windows applications work with &yaz;. The good news is that
1174      you don't have to. You can use the integrated environment of
1175      Visual Studio if desired for your own application.
1176     </para>
1177     <para>
1178      When setting up a project or Makefile you have to set the following:
1179      <variablelist>
1180       <varlistentry>
1181        <term>include path</term>
1182        <listitem><para>
1183         Set it to the <filename>include</filename> directory of &yaz;.
1184         </para></listitem>
1185       </varlistentry>
1186       <varlistentry>
1187        <term>import library <filename>yaz&soversion;.lib</filename></term>
1188        <listitem><para>
1189         You must link with this library. It's located in the
1190         sub directory <filename>lib</filename> of &yaz;.
1191         If you want to link with the debug version of &yaz;, you must
1192         link against <filename>yaz&soversion;d.lib</filename> instead.
1193        </para></listitem>
1194       </varlistentry>
1195       <varlistentry>
1196        <term>dynamic link library
1197        <filename>yaz&soversion;.dll</filename>
1198        </term>
1199        <listitem><para>
1200         This DLL must be in your execution path when you invoke
1201         your application. Specifically, you should distribute this
1202         DLL with your application.
1203        </para></listitem>
1204       </varlistentry>
1205      </variablelist>
1206     </para>
1207    </sect2>
1208
1209    <sect2 id="installation.windows.libxml2">
1210     <title>Compiling Libxml2 and Libxslt on windows</title>
1211     <para>
1212      Download libxml2 and Libxslt source and unpack it.
1213      In the example below we install  Libxml2 2.9.2 and Libxslt 1.1.28
1214      for 32-bit, so we  use the destination directories
1215      libxml2.2.9.2.win32 and libxslt-1.1.28.win32 to reflect both
1216      version and architecture.
1217      <screen>
1218       cd win32
1219       cscript configure.js prefix=c:\libxml2-2.9.2.win32 iconv=no
1220       nmake
1221       nmake install
1222      </screen>
1223     </para>
1224     <note>
1225      <para>
1226       There's an error in <filename>configure.js</filename> for Libxml2 2.9.2.
1227       Line 17 should be assigned to <filename>configure.ac</filename>
1228       rather than <filename>configure.in</filename>.
1229      </para>
1230     </note>
1231     <para>
1232      For Libxslt it is similar. We must ensure that compilation of
1233      Libxslt links against the already installed libxml2.
1234      <screen>
1235       cd win32
1236       cscript configure.js prefix=c:\libxslt-1.1.28.win32 iconv=no \
1237           lib=c:\libxml2-2.9.2.win32\lib \
1238           include=c:\libxml2-2.9.2.win32\include\libxml2
1239       nmake
1240       nmake install
1241      </screen>
1242     </para>
1243    </sect2>
1244
1245   </sect1>
1246  </chapter>
1247  <!--
1248      ### Still to document:
1249      ZOOM_connection_errcode(c)
1250      ZOOM_connection_errmsg(c)
1251      ZOOM_connection_addinfo(c)
1252      ZOOM_connection_addinfo(c)
1253      ZOOM_connection_diagset(c);
1254      ZOOM_connection_save_apdu_wrbuf
1255      ZOOM_diag_str(error)
1256      ZOOM_resultset_record_immediate(s, pos)
1257      ZOOM_resultset_cache_reset(r)
1258      ZOOM_options_set_callback(opt, function, handle)
1259      ZOOM_options_create_with_parent2(parent1, parent2)
1260      ZOOM_options_getl(opt, name, len)
1261      ZOOM_options_setl(opt, name, value, len)
1262      ZOOM_options_get_bool(opt, name, defa)
1263      ZOOM_options_get_int(opt, name, defa)
1264      ZOOM_options_set_int(opt, name, value)
1265  -->
1266  <chapter id="zoom">
1267   <title>ZOOM</title>
1268   <para>
1269    &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is
1270    an initiative started by Mike Taylor (Mike is from the UK, which
1271    explains the peculiar name of the model). The goal of &zoom; is to
1272    provide a common Z39.50 client API not bound to a particular
1273    programming language or toolkit.
1274   </para>
1275   <para>
1276    From YAZ version 2.1.12, <ulink url="&url.sru;">SRU</ulink> is supported.
1277    You can make SRU ZOOM connections by specifying scheme
1278    <literal>http://</literal> for the hostname for a connection.
1279    The dialect of SRU used is specified by the value of the
1280    connection's <literal>sru</literal> option, which may be SRU over
1281    HTTP GET (<literal>get</literal>),
1282    SRU over HTTP POST (<literal>post</literal>), (SRU over
1283    SOAP) (<literal>soap</literal>) or <literal>solr</literal>
1284    (<ulink url="&url.solr;">Solr</ulink> Web Service).
1285    Using the facility for embedding options in target strings, a
1286    connection can be forced to use SRU rather the SRW (the default) by
1287    prefixing the target string with <literal>sru=get,</literal>, like this:
1288    <literal>sru=get,http://sru.miketaylor.org.uk:80/sru.pl</literal>
1289   </para>
1290   <para>
1291    <ulink url="&url.solr;">Solr</ulink>  protocol support was added to
1292    YAZ in version 4.1.0, as a dialect of a SRU protocol, since both are
1293    HTTP based protocols.
1294   </para>
1295   <para>
1296    The lack of a simple Z39.50 client API for &yaz; has become more
1297    and more apparent over time. So when the first &zoom; specification
1298    became available,
1299    an implementation for &yaz; was quickly developed. For the first time, it is
1300    now as easy (or easier!) to develop clients as it is to develop
1301    servers with &yaz;. This
1302    chapter describes the &zoom; C binding. Before going further, please
1303    reconsider whether C is the right programming language for the job.
1304    There are other language bindings available for &yaz;, and still
1305    more
1306    are in active development. See the
1307    <ulink url="&url.zoom;">ZOOM web-site</ulink> for
1308    more information.
1309   </para>
1310   <para>
1311    In order to fully understand this chapter you should read and
1312    try the example programs <literal>zoomtst1.c</literal>,
1313    <literal>zoomtst2.c</literal>, .. in the <literal>zoom</literal>
1314    directory.
1315   </para>
1316   <para>
1317    The C language misses features found in object oriented languages
1318    such as C++, Java, etc. For example, you'll have to manually,
1319    destroy all objects you create, even though you may think of them as
1320    temporary. Most objects have a <literal>_create</literal> - and a
1321    <literal>_destroy</literal> variant.
1322    All objects are in fact pointers to internal stuff, but you don't see
1323    that because of typedefs. All destroy methods should gracefully ignore a
1324    <literal>NULL</literal> pointer.
1325   </para>
1326   <para>
1327    In each of the sections below you'll find a sub section called
1328    protocol behavior, that describes how the API maps to the Z39.50
1329    protocol.
1330   </para>
1331   <sect1 id="zoom-connections">
1332    <title>Connections</title>
1333    <para>The Connection object is a session with a target.
1334    </para>
1335    <synopsis>
1336     #include &lt;yaz/zoom.h>
1337
1338     ZOOM_connection ZOOM_connection_new(const char *host, int portnum);
1339
1340     ZOOM_connection ZOOM_connection_create(ZOOM_options options);
1341
1342     void ZOOM_connection_connect(ZOOM_connection c, const char *host,
1343                                  int portnum);
1344     void ZOOM_connection_destroy(ZOOM_connection c);
1345    </synopsis>
1346    <para>
1347     Connection objects are created with either function
1348     <function>ZOOM_connection_new</function> or
1349     <function>ZOOM_connection_create</function>.
1350     The former creates and automatically attempts to establish a network
1351     connection with the target. The latter doesn't establish
1352     a connection immediately, thus allowing you to specify options
1353     before establishing network connection using the function
1354     <function>ZOOM_connection_connect</function>.
1355     If the port number, <literal>portnum</literal>, is zero, the
1356     <literal>host</literal> is consulted for a port specification.
1357     If no port is given, 210 is used. A colon denotes the beginning of
1358     a port number in the host string. If the host string includes a
1359     slash, the following part specifies a database for the connection.
1360    </para>
1361    <para>
1362     You can prefix the host with a scheme followed by colon. The
1363     default scheme is <literal>tcp</literal> (Z39.50 protocol).
1364     The scheme <literal>http</literal> selects SRU/get over HTTP by default,
1365     but can overridden to use SRU/post, SRW, and the Solr protocol.
1366    </para>
1367    <para>
1368     You can prefix the scheme-qualified host-string with one or more
1369     comma-separated
1370     <literal><parameter>key</parameter>=<parameter>value</parameter></literal>
1371     sequences, each of which represents an option to be set into the
1372     connection structure <emphasis>before</emphasis> the
1373     protocol-level connection is forged and the initialization
1374     handshake takes place.  This facility can be used to provide
1375     authentication credentials, as in host-strings such as:
1376     <literal>user=admin,password=halfAm4n,tcp:localhost:8017/db</literal>
1377    </para>
1378    <para>
1379     Connection objects should be destroyed using the function
1380     <function>ZOOM_connection_destroy</function>.
1381    </para>
1382    <synopsis>
1383     void ZOOM_connection_option_set(ZOOM_connection c,
1384                                     const char *key, const char *val);
1385
1386     void ZOOM_connection_option_setl(ZOOM_connection c,
1387                                      const char *key,
1388                                      const char *val, int len);
1389
1390     const char *ZOOM_connection_option_get(ZOOM_connection c,
1391                                            const char *key);
1392     const char *ZOOM_connection_option_getl(ZOOM_connection c,
1393                                             const char *key,
1394                                             int *lenp);
1395    </synopsis>
1396    <para>
1397     The functions <function>ZOOM_connection_option_set</function> and
1398     <function>ZOOM_connection_option_setl</function> allows you to
1399     set an option given by <parameter>key</parameter> to the value
1400     <parameter>value</parameter> for the connection.
1401     For <function>ZOOM_connection_option_set</function>, the
1402     value is assumed to be a 0-terminated string. Function
1403     <function>ZOOM_connection_option_setl</function> specifies a
1404     value of a certain size (len).
1405    </para>
1406    <para>
1407     Functions <function>ZOOM_connection_option_get</function> and
1408     <function>ZOOM_connection_option_getl</function> returns
1409     the value for an option given by <parameter>key</parameter>.
1410    </para>
1411    <table id="zoom-connection-options" frame="top">
1412     <title>ZOOM Connection Options</title>
1413     <tgroup cols="3">
1414      <colspec colwidth="4*" colname="name"></colspec>
1415      <colspec colwidth="7*" colname="description"></colspec>
1416      <colspec colwidth="3*" colname="default"></colspec>
1417      <thead>
1418       <row>
1419        <entry>Option</entry>
1420        <entry>Description</entry>
1421        <entry>Default</entry>
1422       </row>
1423      </thead>
1424      <tbody>
1425       <row><entry>
1426        implementationName</entry><entry>Name of Your client
1427       </entry><entry>none</entry></row>
1428       <row><entry>
1429        user</entry><entry>Authentication user name
1430       </entry><entry>none</entry></row>
1431       <row><entry>
1432        group</entry><entry>Authentication group name
1433       </entry><entry>none</entry></row>
1434       <row><entry>
1435        password</entry><entry>Authentication password.
1436       </entry><entry>none</entry></row>
1437       <row><entry>
1438        authenticationMode</entry><entry>How authentication is encoded.
1439       </entry><entry>basic</entry></row>
1440       <row><entry>
1441        host</entry><entry>Target host. This setting is "read-only".
1442        It's automatically set internally when connecting to a target.
1443       </entry><entry>none</entry></row>
1444       <row><entry>
1445        proxy</entry><entry>Proxy host. If set, the logical host
1446        is encoded in the otherInfo area of the Z39.50 Init PDU
1447        with OID 1.2.840.10003.10.1000.81.1.
1448       </entry><entry>none</entry></row>
1449       <row><entry>
1450        clientIP</entry><entry>Client IP. If set, is
1451        encoded in the otherInfo area of a Z39.50 PDU with OID
1452        1.2.840.10003.10.1000.81.3. Holds the original IP addreses
1453        of a client. Is used if ZOOM is used in a gateway of some sort.
1454       </entry><entry>none</entry></row>
1455       <row><entry>
1456        async</entry><entry>If true (1) the connection operates in
1457        asynchronous operation which means that all calls are non-blocking
1458        except
1459        <link linkend="zoom.events"><function>ZOOM_event</function></link>.
1460       </entry><entry>0</entry></row>
1461       <row><entry>
1462        maximumRecordSize</entry><entry> Maximum size of single record.
1463       </entry><entry>1 MB</entry></row>
1464       <row><entry>
1465        preferredMessageSize</entry><entry> Maximum size of multiple records.
1466       </entry><entry>1 MB</entry></row>
1467       <row><entry>
1468        lang</entry><entry> Language for negotiation.
1469       </entry><entry>none</entry></row>
1470       <row><entry>
1471        charset</entry><entry> Character set for negotiation.
1472       </entry><entry>none</entry></row>
1473       <row><entry>
1474        serverImplementationId</entry><entry>
1475        Implementation ID of server.  (The old targetImplementationId
1476        option is also supported for the benefit of old applications.)
1477       </entry><entry>none</entry></row>
1478       <row><entry>
1479        targetImplementationName</entry><entry>
1480        Implementation Name of server.  (The old
1481        targetImplementationName option is also supported for the
1482        benefit of old applications.)
1483       </entry><entry>none</entry></row>
1484       <row><entry>
1485        serverImplementationVersion</entry><entry>
1486        Implementation Version of server.  (the old
1487        targetImplementationVersion option is also supported for the
1488        benefit of old applications.)
1489       </entry><entry>none</entry></row>
1490       <row><entry>
1491        databaseName</entry><entry>One or more database names
1492        separated by character plus (<literal>+</literal>), which is to
1493        be used by subsequent search requests on this Connection.
1494       </entry><entry>Default</entry></row>
1495       <row><entry>
1496        piggyback</entry><entry>True (1) if piggyback should be
1497        used in searches; false (0) if not.
1498       </entry><entry>1</entry></row>
1499       <row><entry>
1500        smallSetUpperBound</entry><entry>If hits is less than or equal to this
1501        value, then target will return all records using small element set name
1502       </entry><entry>0</entry></row>
1503       <row><entry>
1504        largeSetLowerBound</entry><entry>If hits is greater than this
1505        value, the target will return no records.
1506       </entry><entry>1</entry></row>
1507       <row><entry>
1508        mediumSetPresentNumber</entry><entry>This value represents
1509        the number of records to be returned as part of a search when
1510        hits is less than or equal to large set lower bound and if hits
1511        is greater than small set upper bound.
1512       </entry><entry>0</entry></row>
1513       <row><entry>
1514        smallSetElementSetName</entry><entry>
1515        The element set name to be used for small result sets.
1516       </entry><entry>none</entry></row>
1517       <row><entry>
1518        mediumSetElementSetName</entry><entry>
1519        The element set name to be used for medium-sized result sets.
1520       </entry><entry>none</entry></row>
1521       <row><entry>
1522        init_opt_search, init_opt_present, init_opt_delSet, etc.</entry><entry>
1523        After a successful Init, these options may be interrogated to
1524        discover whether the server claims to support the specified
1525        operations.
1526       </entry><entry>none</entry></row>
1527       <row>
1528        <entry>sru</entry><entry>
1529        SRU/Solr transport type. Must be either <literal>soap</literal>,
1530        <literal>get</literal>, <literal>post</literal>, or
1531        <literal>solr</literal>.
1532       </entry><entry>soap</entry></row>
1533       <row><entry>
1534        sru_version</entry><entry>
1535        SRU/SRW version. Should be <literal>1.1</literal>, or
1536        <literal>1.2</literal>. This is, prior to connect, the version
1537        to offer (highest version). And following connect (in fact
1538        first operation), holds the negotiated version with the server
1539        (same or lower version).
1540       </entry><entry>1.2</entry></row>
1541       <row id="zoom.extraArgs.option"><entry>
1542        extraArgs</entry><entry>
1543        Extra arguments for SRU/Solr URLs. The value must be
1544        URL encoded already.
1545       </entry><entry></entry></row>
1546       <row id="zoom.facets.option"><entry>
1547        facets</entry><entry>
1548        Requested or recommended facets may be given before a search is sent.
1549        The value of this setting is described in <xref linkend="facets"/>
1550        For inspection of the facets returned, refer to the functions
1551        described in <xref linkend="zoom.facets"/>.
1552       </entry><entry>none</entry></row>
1553       <row><entry>
1554        apdulog</entry><entry>
1555        If set to a true value such as "1", a log of low-level
1556        protocol packets is emitted on standard error stream.  This
1557        can be very useful for debugging.
1558       </entry><entry>0</entry></row>
1559       <row><entry>
1560        saveAPDU</entry><entry>
1561        If set to a true value such as "1", a log of low-level
1562        protocol packets is saved. The log can be retrieved by reading
1563        option APDU. Setting saveAPDU always has the side effect of
1564        resetting the currently saved log. This setting is
1565        <emphasis>write-only</emphasis>. If read, NULL will be returned.
1566        It is only recognized in
1567        <function>ZOOM_connection_option_set</function>.
1568       </entry><entry>0</entry></row>
1569       <row><entry>
1570        APDU</entry><entry>
1571        Returns the log of protocol packets. Will be empty if logging
1572        is not enabled (see saveAPDU above). This setting is
1573        <emphasis>read-only</emphasis>. It is only recognized if used
1574        in call to <function>ZOOM_connection_option_get</function> or
1575        <function>ZOOM_connection_option_getl</function>.
1576       </entry><entry></entry></row>
1577       <row><entry>
1578        memcached</entry><entry>
1579        If given and non-empty,
1580        <ulink url="&url.libmemcached;">libMemcached</ulink>
1581        will be configured for the connection.
1582        This option is inspected by ZOOM when a connection is established.
1583        If the <literal>memcached</literal> option is given
1584        and YAZ is compiled without libMemcached support, an internal
1585        diagnostic (10018) will be thrown.
1586        libMemcached support is available for YAZ 5.0.13 or later. If this
1587        option is supplied for an earlier version of YAZ, it is
1588        <emphasis>ignored</emphasis>.
1589        The value of this option is a list options - each is of the
1590        form <literal>--name=value</literal>.
1591        Option <literal>--server=</literal>host[:port] specifies a memcached
1592        server. It may be repeated for multiple memcached servers.
1593        Option <literal>--expire=</literal>seconds sets expiry time in seconds
1594        for how long result sets are to be cached.
1595       </entry><entry>none</entry></row>
1596       <row><entry>
1597        redis</entry><entry>
1598        If given and non-empty,
1599        a <ulink url="&url.redis;">redis</ulink> context will be created
1600        for the connection.
1601        This option is inspected by ZOOM when a connection is established.
1602        If the <literal>redis</literal> option is given
1603        and YAZ is compiled without redis support, an internal
1604        diagnostic (10018) will be thrown.
1605        redis support is available for YAZ 5.2.0 or later. If this
1606        option is supplied for an earlier version of YAZ, it is
1607        <emphasis>ignored</emphasis>.
1608        The value of this option is a set of options, similar to that
1609        of the memcached setting. At this stage only --server=host[:port]
1610        and --expire=seconds are supported.
1611       </entry><entry>none</entry></row>
1612      </tbody>
1613     </tgroup>
1614    </table>
1615    <para>
1616     If either option <literal>lang</literal> or <literal>charset</literal>
1617     is set, then
1618     <ulink url="&url.z39.50.charneg;">
1619      Character Set and Language Negotiation</ulink> is in effect.
1620    </para>
1621    <synopsis>
1622      int ZOOM_connection_error(ZOOM_connection c, const char **cp,
1623                                const char **addinfo);
1624      int ZOOM_connection_error_x(ZOOM_connection c, const char **cp,
1625                                  const char **addinfo, const char **dset);
1626    </synopsis>
1627    <para>
1628     Function <function>ZOOM_connection_error</function> checks for
1629     errors for the last operation(s) performed. The function returns
1630     zero if no errors occurred; non-zero otherwise indicating the error.
1631     Pointers <parameter>cp</parameter> and <parameter>addinfo</parameter>
1632     holds messages for the error and additional-info if passed as
1633     non-<literal>NULL</literal>. Function
1634     <function>ZOOM_connection_error_x</function> is an extended version
1635     of <function>ZOOM_connection_error</function> that is capable of
1636     returning name of diagnostic set in <parameter>dset</parameter>.
1637    </para>
1638    <sect2 id="zoom-connection-z39.50">
1639     <title>Z39.50 Protocol behavior</title>
1640     <para>
1641      The calls <function>ZOOM_connection_new</function> and
1642      <function>ZOOM_connection_connect</function> establishes a TCP/IP
1643      connection and sends an Initialize Request to the target if
1644      possible. In addition, the calls wait for an Initialize Response
1645      from the target and the result is inspected (OK or rejected).
1646     </para>
1647     <para>
1648      If <literal>proxy</literal> is set then the client will establish
1649      a TCP/IP connection with the peer as specified by the
1650      <literal>proxy</literal> host and the hostname as part of the
1651      connect calls will be set as part of the Initialize Request.
1652      The proxy server will then "forward" the PDU's transparently
1653      to the target behind the proxy.
1654     </para>
1655     <para>
1656      For the authentication parameters, if option <literal>user</literal>
1657      is set and both options <literal>group</literal> and
1658      <literal>pass</literal> are unset, then Open style
1659      authentication is used (Version 2/3) in which case the username
1660      is usually followed by a slash, then by a password.
1661      If either <literal>group</literal>
1662      or <literal>pass</literal> is set then idPass authentication
1663      (Version 3 only) is used. If none of the options are set, no
1664      authentication parameters are set as part of the Initialize Request
1665      (obviously).
1666     </para>
1667     <para>
1668      When option <literal>async</literal> is 1, it really means that
1669      all network operations are postponed (and queued) until the
1670      function <literal>ZOOM_event</literal> is invoked. When doing so
1671      it doesn't make sense to check for errors after
1672      <literal>ZOOM_connection_new</literal> is called since that
1673      operation "connecting - and init" is still incomplete and the
1674      API cannot tell the outcome (yet).
1675     </para>
1676     </sect2>
1677    <sect2 id="zoom.sru.init.behavior">
1678     <title>SRU/Solr Protocol behavior</title>
1679     <para>
1680      The HTTP based protocols (SRU, SRW, Solr) do not feature an
1681      Inititialize Request, so  the connection phase merely establishes a
1682      TCP/IP connection with the HTTP server.
1683     </para>
1684     <para>Most of the ZOOM connection options do not
1685      affect SRU/Solr and they are ignored. However, future versions
1686      of &yaz; might honor <literal>implementationName</literal> and
1687      put that as part of User-Agent header for HTTP requests.
1688      </para>
1689     <para>
1690      The <literal>charset</literal> is used in the Content-Type header
1691      of HTTP requests.
1692     </para>
1693     <para>
1694      Setting <literal>authentcationMode</literal> specifies how
1695      authentication parameters are encoded for HTTP. The default is
1696      "<literal>basic</literal>" where <literal>user</literal> and
1697      <literal>password</literal> are encoded by using HTTP basic
1698      authentication.
1699      </para>
1700     <para>
1701      If <literal>authentcationMode</literal> is "<literal>url</literal>", then
1702      user and password are encoded in the URL by parameters
1703      <literal>x-username</literal> and <literal>x-password</literal> as
1704      given by the SRU standard.
1705     </para>
1706    </sect2>
1707   </sect1>
1708   <sect1 id="zoom.query">
1709    <title>Queries</title>
1710    <para>
1711     Query objects represents queries.
1712    </para>
1713    <synopsis>
1714      ZOOM_query ZOOM_query_create(void);
1715
1716      void ZOOM_query_destroy(ZOOM_query q);
1717
1718      int ZOOM_query_prefix(ZOOM_query q, const char *str);
1719
1720      int ZOOM_query_cql(ZOOM_query s, const char *str);
1721
1722      int ZOOM_query_sortby(ZOOM_query q, const char *criteria);
1723
1724      int ZOOM_query_sortby2(ZOOM_query q, const char *strategy,
1725                             const char *criteria);
1726    </synopsis>
1727    <para>
1728     Create query objects using <function>ZOOM_query_create</function>
1729     and destroy them by calling <function>ZOOM_query_destroy</function>.
1730     RPN-queries can be specified in <link linkend="PQF">PQF</link>
1731     notation by using the
1732     function <function>ZOOM_query_prefix</function>.
1733     The <function>ZOOM_query_cql</function> specifies a CQL
1734     query to be sent to the server/target.
1735     More query types will be added in future versions of &yaz;, such as
1736     <link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
1737     etc. In addition to a search, a sort criteria may be set. Function
1738     <function>ZOOM_query_sortby</function> enables Z39.50 sorting and
1739     it takes sort criteria using the same string notation as
1740     yaz-client's <link linkend="sortspec">sort command</link>.
1741    </para>
1742    <para id="zoom.query.sortby2">
1743     <function>ZOOM_query_sortby2</function> is similar to
1744     <function>ZOOM_query_sortby</function> but allows a strategy for
1745     sorting. The reason for the strategy parameter is that some
1746     protocols offer multiple ways of performing sorting.
1747     For example, Z39.50 has the standard sort, which is performed after
1748     search on an existing result set.
1749     It's also possible to use CQL in Z39.50 as the query type and use
1750     CQL's SORTBY keyword. Finally, Index Data's
1751     Zebra server also allows sorting to be specified as part of RPN (Type 7).
1752    </para>
1753    <table id="zoom-sort-strategy" frame="top">
1754     <title>ZOOM sort strategy</title>
1755     <tgroup cols="2">
1756      <colspec colwidth="2*" colname="name"/>
1757      <colspec colwidth="5*" colname="description"/>
1758      <thead>
1759       <row>
1760        <entry>Name</entry>
1761        <entry>Description</entry>
1762       </row>
1763      </thead>
1764      <tbody>
1765       <row>
1766        <entry>z39.50</entry><entry>Z39.50 resultset sort</entry>
1767       </row>
1768       <row>
1769        <entry>type7</entry><entry>Sorting embedded in RPN(Type-7)</entry>
1770       </row>
1771       <row>
1772        <entry>cql</entry><entry>CQL SORTBY</entry>
1773       </row>
1774       <row>
1775        <entry>sru11</entry><entry>SRU sortKeys parameter</entry>
1776       </row>
1777       <row>
1778        <entry>solr</entry><entry>Solr sort</entry>
1779       </row>
1780       <row>
1781        <entry>embed</entry><entry>type7 for Z39.50, cql for SRU,
1782         solr for Solr protocol</entry>
1783       </row>
1784      </tbody>
1785     </tgroup>
1786    </table>
1787   </sect1>
1788   <sect1 id="zoom.resultsets"><title>Result sets</title>
1789    <para>
1790     The result set object is a container for records returned from
1791     a target.
1792    </para>
1793    <synopsis>
1794      ZOOM_resultset ZOOM_connection_search(ZOOM_connection, ZOOM_query q);
1795
1796      ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c,
1797                                                const char *q);
1798      void ZOOM_resultset_destroy(ZOOM_resultset r);
1799    </synopsis>
1800    <para>
1801     Function <function>ZOOM_connection_search</function> creates
1802     a result set, given a connection and query.
1803     Destroy a result set by calling
1804     <function>ZOOM_resultset_destroy</function>.
1805     Simple clients using PQF only, may use the function
1806     <function>ZOOM_connection_search_pqf</function> in which case
1807     creating query objects is not necessary.
1808    </para>
1809    <synopsis>
1810      void ZOOM_resultset_option_set(ZOOM_resultset r,
1811                                     const char *key, const char *val);
1812
1813      const char *ZOOM_resultset_option_get(ZOOM_resultset r, const char *key);
1814
1815      size_t ZOOM_resultset_size(ZOOM_resultset r);
1816    </synopsis>
1817    <para>
1818     Functions <function>ZOOM_resultset_options_set</function> and
1819     <function>ZOOM_resultset_get</function> sets and gets an option
1820     for a result set similar to <function>ZOOM_connection_option_get</function>
1821     and <function>ZOOM_connection_option_set</function>.
1822    </para>
1823    <para>
1824     The number of hits, also called result-count, is returned by
1825     function <function>ZOOM_resultset_size</function>.
1826    </para>
1827    <table id="zoom.resultset.options"
1828     frame="top"><title>ZOOM Result set Options</title>
1829     <tgroup cols="3">
1830      <colspec colwidth="4*" colname="name"></colspec>
1831      <colspec colwidth="7*" colname="description"></colspec>
1832      <colspec colwidth="2*" colname="default"></colspec>
1833      <thead>
1834       <row>
1835        <entry>Option</entry>
1836        <entry>Description</entry>
1837        <entry>Default</entry>
1838       </row>
1839      </thead>
1840      <tbody>
1841       <row><entry>
1842         start</entry><entry>Offset of first record to be
1843         retrieved from target. First record has offset 0 unlike the
1844         protocol specifications where first record has position 1.
1845         This option affects ZOOM_resultset_search and
1846         ZOOM_resultset_search_pqf and must be set before any of
1847         these functions are invoked. If a range of
1848         records must be fetched manually after search,
1849         function ZOOM_resultset_records should be used.
1850        </entry><entry>0</entry></row>
1851       <row><entry>
1852         count</entry><entry>Number of records to be retrieved.
1853         This option affects ZOOM_resultset_search and
1854         ZOOM_resultset_search_pqf and must be set before any of
1855         these functions are invoked.
1856        </entry><entry>0</entry></row>
1857       <row><entry>
1858         presentChunk</entry><entry>The number of records to be
1859         requested from the server in each chunk (present request). The
1860         value 0 means to request all the records in a single chunk.
1861         (The old <literal>step</literal>
1862         option is also supported for the benefit of old applications.)
1863        </entry><entry>0</entry></row>
1864       <row><entry>
1865         elementSetName</entry><entry>Element-Set name of records.
1866         Most targets should honor element set name <literal>B</literal>
1867         and <literal>F</literal> for brief and full respectively.
1868        </entry><entry>none</entry></row>
1869       <row><entry>
1870         preferredRecordSyntax</entry><entry>Preferred Syntax, such as
1871         <literal>USMARC</literal>, <literal>SUTRS</literal>, etc.
1872        </entry><entry>none</entry></row>
1873       <row><entry>
1874         schema</entry><entry>Schema for retrieval, such as
1875         <literal>Gils-schema</literal>, <literal>Geo-schema</literal>, etc.
1876        </entry><entry>none</entry></row>
1877       <row><entry>
1878         setname</entry><entry>Name of Result Set (Result Set ID).
1879         If this option isn't set, the ZOOM module will automatically
1880         allocate a result set name.
1881        </entry><entry>default</entry></row>
1882       <row><entry>
1883         rpnCharset</entry><entry>Character set for RPN terms.
1884         If this is set, ZOOM C will assume that the ZOOM application is
1885         running UTF-8. Terms in RPN queries are then converted to the
1886         rpnCharset. If this is unset, ZOOM C will not assume any encoding
1887         of RPN terms and no conversion is performed.
1888        </entry><entry>none</entry></row>
1889      </tbody>
1890     </tgroup>
1891    </table>
1892    <para>
1893     For servers that support Search Info report, the following
1894     options may be read using <function>ZOOM_resultset_get</function>.
1895     This detailed information is read after a successful search has
1896     completed.
1897    </para>
1898    <para>
1899     This information is a list of of items, where each item is
1900     information about a term or subquery. All items in the list
1901     are prefixed by
1902     <literal>SearchResult.</literal><replaceable>no</replaceable>
1903     where no presents the item number (0=first, 1=second).
1904     Read <literal>searchresult.size</literal> to determine the
1905     number of items.
1906    </para>
1907    <table id="zoom.search.info.report.options"
1908     frame="top"><title>Search Info Report Options</title>
1909     <tgroup cols="2">
1910      <colspec colwidth="4*" colname="name"></colspec>
1911      <colspec colwidth="7*" colname="description"></colspec>
1912      <thead>
1913       <row>
1914        <entry>Option</entry>
1915        <entry>Description</entry>
1916       </row>
1917      </thead>
1918      <tbody>
1919       <row>
1920        <entry>searchresult.size</entry>
1921        <entry>
1922         number of search result entries. This option is non-existent
1923         if no entries are returned by the server.
1924        </entry>
1925       </row>
1926       <row>
1927        <entry>searchresult.<replaceable>no</replaceable>.id</entry>
1928        <entry>sub query ID</entry>
1929       </row>
1930       <row>
1931        <entry>searchresult.<replaceable>no</replaceable>.count</entry>
1932        <entry>result count for item (number of hits)</entry>
1933       </row>
1934       <row>
1935        <entry>searchresult.<replaceable>no</replaceable>.subquery.term</entry>
1936        <entry>subquery term</entry>
1937       </row>
1938       <row>
1939        <entry>
1940         searchresult.<replaceable>no</replaceable>.interpretation.term
1941        </entry>
1942        <entry>interpretation term</entry>
1943       </row>
1944       <row>
1945        <entry>
1946         searchresult.<replaceable>no</replaceable>.recommendation.term
1947        </entry>
1948        <entry>recommendation term</entry>
1949       </row>
1950      </tbody>
1951     </tgroup>
1952    </table>
1953    <sect2 id="zoom.z3950.resultset.sort">
1954     <title>Z39.50 Result-set Sort</title>
1955     <synopsis>
1956      void ZOOM_resultset_sort(ZOOM_resultset r,
1957                               const char *sort_type, const char *sort_spec);
1958
1959      int ZOOM_resultset_sort1(ZOOM_resultset r,
1960                               const char *sort_type, const char *sort_spec);
1961     </synopsis>
1962     <para>
1963      <function>ZOOM_resultset_sort</function> and
1964      <function>ZOOM_resultset_sort1</function> both sort an existing
1965      result-set. The sort_type parameter is not used. Set it to "yaz".
1966      The sort_spec is same notation as ZOOM_query_sortby and identical
1967      to that offered by yaz-client's
1968      <link linkend="sortspec">sort command</link>.
1969     </para>
1970     <para>
1971      These functions only work for Z39.50. Use the more generic utility
1972      <link linkend="zoom.query.sortby2">
1973       <function>ZOOM_query_sortby2</function></link>
1974      for other protocols (and even Z39.50).
1975     </para>
1976    </sect2>
1977    <sect2 id="zoom.z3950.resultset.behavior">
1978     <title>Z39.50 Protocol behavior</title>
1979     <para>
1980      The creation of a result set involves at least a SearchRequest
1981      - SearchResponse protocol handshake. Following that, if a sort
1982      criteria was specified as part of the query, a SortRequest -
1983      SortResponse handshake takes place. Note that it is necessary to
1984      perform sorting before any retrieval takes place, so no records will
1985      be returned from the target as part of the SearchResponse because these
1986      would be unsorted. Hence, piggyback is disabled when sort criteria
1987      are set. Following Search - and a possible sort - Retrieval takes
1988      place - as one or more Present Requests/Response pairs being
1989      transferred.
1990      </para>
1991     <para>
1992      The API allows for two different modes for retrieval. A high level
1993      mode which is somewhat more powerful and a low level one.
1994      The low level is enabled when searching on a Connection object
1995      for which the settings
1996      <literal>smallSetUpperBound</literal>,
1997      <literal>mediumSetPresentNumber</literal> and
1998      <literal>largeSetLowerBound</literal> are set. The low level mode
1999      thus allows you to precisely set how records are returned as part
2000      of a search response as offered by the Z39.50 protocol.
2001      Since the client may be retrieving records as part of the
2002      search response, this mode doesn't work well if sorting is used.
2003      </para>
2004     <para>
2005      The high-level mode allows you to fetch a range of records from
2006      the result set with a given start offset. When you use this mode
2007      the client will automatically use piggyback if that is possible
2008      with the target, and perform one or more present requests as needed.
2009      Even if the target returns fewer records as part of a present response
2010      because of a record size limit, etc. the client will repeat sending
2011      present requests. As an example, if option <literal>start</literal>
2012      is 0 (default) and <literal>count</literal> is 4, and
2013      <literal>piggyback</literal> is 1 (default) and no sorting criteria
2014      is specified, then the client will attempt to retrieve the 4
2015      records as part the search response (using piggyback). On the other
2016      hand, if either <literal>start</literal> is positive or if
2017      a sorting criteria is set, or if <literal>piggyback</literal>
2018      is 0, then the client will not perform piggyback but send Present
2019      Requests instead.
2020     </para>
2021     <para>
2022      If either of the options <literal>mediumSetElementSetName</literal> and
2023      <literal>smallSetElementSetName</literal> are unset, the value
2024      of option <literal>elementSetName</literal> is used for piggyback
2025      searches. This means that for the high-level mode you only have
2026      to specify one elementSetName option rather than three.
2027      </para>
2028    </sect2>
2029    <sect2 id="zoom.sru.resultset.behavior">
2030     <title>SRU Protocol behavior</title>
2031     <para>
2032      Current version of &yaz; does not take advantage of a result set id
2033      returned by the SRU server. Future versions might do, however.
2034      Since the ZOOM driver does not save result set IDs, any
2035      present (retrieval) is transformed to a SRU SearchRetrieveRequest
2036      with same query but, possibly, different offsets.
2037     </para>
2038     <para>
2039      Option <literal>schema</literal> specifies SRU schema
2040      for retrieval. However, options <literal>elementSetName</literal> and
2041      <literal>preferredRecordSyntax</literal> are ignored.
2042     </para>
2043     <para>
2044      Options <literal>start</literal> and <literal>count</literal>
2045      are supported by SRU.
2046      The remaining options
2047      <literal>piggyback</literal>,
2048      <literal>smallSetUpperBound</literal>,
2049      <literal>largeSetLowerBound</literal>,
2050      <literal>mediumSetPresentNumber</literal>,
2051      <literal>mediumSetElementSetName</literal>,
2052       <literal>smallSetElementSetName</literal> are
2053      unsupported.
2054     </para>
2055     <para>
2056      SRU supports CQL queries, <emphasis>not</emphasis> PQF.
2057      If PQF is used, however, the PQF query is transferred anyway
2058      using non-standard element <literal>pQuery</literal> in
2059      SRU SearchRetrieveRequest.
2060     </para>
2061     <para>
2062      Solr queries need to be done in Solr query format.
2063     </para>
2064     <para>
2065      Unfortunately, SRU and Solr do not define a database setting. Hence,
2066      <literal>databaseName</literal> is unsupported and ignored.
2067      However, the path part in host parameter for functions
2068      <function>ZOOM_connecton_new</function> and
2069      <function>ZOOM_connection_connect</function> acts as a
2070      database (at least for the &yaz; SRU server).
2071     </para>
2072    </sect2>
2073   </sect1>
2074   <sect1 id="zoom.records">
2075    <title>Records</title>
2076    <para>
2077     A record object is a retrieval record on the client side -
2078     created from result sets.
2079    </para>
2080    <synopsis>
2081      void ZOOM_resultset_records(ZOOM_resultset r,
2082                                  ZOOM_record *recs,
2083                                  size_t start, size_t count);
2084      ZOOM_record ZOOM_resultset_record(ZOOM_resultset s, size_t pos);
2085
2086      const char *ZOOM_record_get(ZOOM_record rec, const char *type,
2087                                  size_t *len);
2088
2089      int ZOOM_record_error(ZOOM_record rec, const char **msg,
2090                            const char **addinfo, const char **diagset);
2091
2092      ZOOM_record ZOOM_record_clone(ZOOM_record rec);
2093
2094      void ZOOM_record_destroy(ZOOM_record rec);
2095    </synopsis>
2096    <para>
2097     References to temporary records are returned by functions
2098     <function>ZOOM_resultset_records</function> or
2099     <function>ZOOM_resultset_record</function>.
2100     </para>
2101    <para>
2102     If a persistent reference to a record is desired
2103     <function>ZOOM_record_clone</function> should be used.
2104     It returns a record reference that should be destroyed
2105     by a call to <function>ZOOM_record_destroy</function>.
2106    </para>
2107    <para>
2108     A single record is returned by function
2109     <function>ZOOM_resultset_record</function> that takes a
2110     position as argument. First record has position zero.
2111     If no record could be obtained <literal>NULL</literal> is returned.
2112    </para>
2113    <para>
2114     Error information for a record can be checked with
2115     <function>ZOOM_record_error</function> which returns non-zero
2116     (error code) if record is in error, called <emphasis>Surrogate
2117      Diagnostics</emphasis> in Z39.50.
2118    </para>
2119    <para>
2120     Function <function>ZOOM_resultset_records</function> retrieves
2121     a number of records from a result set. Parameter <literal>start</literal>
2122     and <literal>count</literal> specifies the range of records to
2123     be returned. Upon completion, the array
2124     <literal>recs[0], ..recs[count-1]</literal>
2125     holds record objects for the records. The array of records
2126      <literal>recs</literal> should be allocated prior the call
2127     <function>ZOOM_resultset_records</function>. Note that for those
2128     records that couldn't be retrieved from the target,
2129     <literal>recs[ ..]</literal> is set to <literal>NULL</literal>.
2130    </para>
2131    <para id="zoom.record.get">
2132     In order to extract information about a single record,
2133     <function>ZOOM_record_get</function> is provided. The
2134     function returns a pointer to certain record information. The
2135     nature (type) of the pointer depends on the parameter,
2136     <parameter>type</parameter>.
2137    </para>
2138    <para>
2139     The <parameter>type</parameter> is a string of the format:
2140    </para>
2141    <para>
2142     <replaceable>format</replaceable>[;charset=<replaceable>from</replaceable>[/<replaceable>opacfrom</replaceable>][,<replaceable>to</replaceable>]][;format=<replaceable>v</replaceable>][;base64=<replaceable>xpath</replaceable>]
2143    </para>
2144    <para>
2145     If <literal>charset</literal> is given, then <replaceable>from</replaceable>
2146     specifies the character set of the record in its original form
2147     (as returned by the server), <replaceable>to</replaceable> specifies
2148     the output (returned) character set encoding.
2149     If <replaceable>to</replaceable> is omitted, then UTF-8 is assumed.
2150     If charset is not given, then no character set conversion takes place.
2151     OPAC records may be returned in a different
2152     set from the bibliographic MARC record. If this is this the case,
2153     <replaceable>opacfrom</replaceable> should be set to the character set
2154     of the OPAC record part.
2155    </para>
2156
2157    <para>
2158     The <literal>format</literal> is generic but can only be used to
2159     specify XML indentation when the value <replaceable>v</replaceable>
2160     is 1 (<literal>format=1</literal>).
2161    </para>
2162    <para>
2163     The <literal>base64</literal> allows a full record to be extracted
2164     from base64-encoded string in an XML document.
2165    </para>
2166    <note>
2167      <para>
2168        Specifying the OPAC record character set requires YAZ 4.1.5 or later.
2169      </para>
2170      <para>
2171        Specifying the base64 parameter requires YAZ 4.2.35 or later.
2172      </para>
2173    </note>
2174    <para>
2175     The format argument controls whether record data should be XML
2176     pretty-printed (post process operation).
2177     It is enabled only if format value <replaceable>v</replaceable> is
2178     <literal>1</literal> and the record content is XML well-formed.
2179    </para>
2180    <para>
2181     In addition, for certain types, the length
2182     <literal>len</literal> passed will be set to the size in bytes of
2183     the returned information.
2184     </para>
2185    <para>
2186     The following are the supported values for <replaceable>form</replaceable>.
2187     <variablelist>
2188      <varlistentry><term><literal>database</literal></term>
2189       <listitem><para>The Database of the record is returned
2190         as a C null-terminated string. Return type
2191         <literal>const char *</literal>.
2192        </para></listitem>
2193      </varlistentry>
2194      <varlistentry><term><literal>syntax</literal></term>
2195       <listitem><para>The transfer syntax of the record is returned
2196         as a C null-terminated string containing the symbolic name of
2197         the record syntax, e.g. <literal>Usmarc</literal>. Return type
2198         is
2199         <literal>const char *</literal>.
2200        </para></listitem>
2201      </varlistentry>
2202      <varlistentry><term><literal>schema</literal></term>
2203       <listitem><para>The schema of the record is returned
2204         as a C null-terminated string. Return type is
2205         <literal>const char *</literal>.
2206        </para></listitem>
2207      </varlistentry>
2208      <varlistentry><term><literal>render</literal></term>
2209       <listitem><para>The record is returned in a display friendly
2210         format. Upon completion, buffer is returned
2211         (type <literal>const char *</literal>) and length is stored in
2212         <literal>*len</literal>.
2213        </para></listitem>
2214      </varlistentry>
2215      <varlistentry><term><literal>raw</literal></term>
2216       <listitem><para>The record is returned in the internal
2217         YAZ specific format. For GRS-1, Explain, and others, the
2218         raw data is returned as type
2219         <literal>Z_External *</literal> which is just the type for
2220         the member <literal>retrievalRecord</literal> in
2221         type <literal>NamePlusRecord</literal>.
2222         For SUTRS and octet aligned record (including all MARCs) the
2223         octet buffer is returned and the length of the buffer.
2224        </para></listitem>
2225      </varlistentry>
2226      <varlistentry><term><literal>xml</literal></term>
2227       <listitem><para>The record is returned in XML if possible.
2228         SRU, Solr and Z39.50 records with transfer syntax XML are
2229         returned verbatim. MARC records are returned in
2230         <ulink url="&url.marcxml;">
2231          MARCXML
2232          </ulink>
2233         (converted from ISO2709 to MARCXML by YAZ).
2234         OPAC records are also converted to XML and the
2235         bibliographic record is converted to MARCXML (when possible).
2236         GRS-1 records are not supported for this form.
2237         Upon completion, the XML buffer is returned
2238         (type <literal>const char *</literal>) and length is stored in
2239         <literal>*len</literal>.
2240        </para></listitem>
2241      </varlistentry>
2242      <varlistentry><term><literal>opac</literal></term>
2243       <listitem><para>OPAC information for record is returned in XML
2244         if an OPAC record is present at the position given. If no
2245         OPAC record is present, a NULL pointer is returned.
2246        </para></listitem>
2247      </varlistentry>
2248      <varlistentry><term><literal>txml</literal></term>
2249       <listitem><para>The record is returned in TurboMARC if possible.
2250         SRU and Z39.50 records with transfer syntax XML are
2251         returned verbatim. MARC records are returned in
2252         <link linkend="tools.turbomarc">
2253          TurboMARC
2254         </link>
2255         (converted from ISO2709 to TurboMARC by YAZ).
2256         Upon completion, the XML buffer is returned
2257         (type <literal>const char *</literal>) and length is stored in
2258         <literal>*len</literal>.
2259        </para></listitem>
2260      </varlistentry>
2261      <varlistentry><term><literal>json</literal></term>
2262       <listitem><para>Like xml, but MARC records are converted to
2263         <ulink url="&url.marc_in_json;">MARC-in-JSON</ulink>.
2264        </para></listitem>
2265      </varlistentry>
2266
2267     </variablelist>
2268    </para>
2269    <para>
2270     Most
2271     <ulink url="&url.marc21;">MARC21</ulink>
2272     records uses the
2273     <ulink url="&url.marc8;">MARC-8</ulink>
2274     character set encoding.
2275     An application that wishes to display in Latin-1 would use
2276     <screen>
2277      render; charset=marc8,iso-8859-1
2278     </screen>
2279    </para>
2280    <sect2 id="zoom.z3950.record.behavior">
2281     <title>Z39.50 Protocol behavior</title>
2282     <para>
2283      The functions <function>ZOOM_resultset_record</function> and
2284      <function>ZOOM_resultset_records</function> inspects the client-side
2285      record cache. Records not found in cache are fetched using
2286      Present.
2287      The functions may block (and perform network I/O)  - even though option
2288      <literal>async</literal> is 1, because they return records objects.
2289      (And there's no way to return records objects without retrieving them!)
2290      </para>
2291     <para>
2292      There is a trick, however, in the usage of function
2293      <function>ZOOM_resultset_records</function> that allows for
2294      delayed retrieval (and makes it non-blocking). By using
2295      a null pointer for <parameter>recs</parameter> you're indicating
2296      you're not interested in getting records objects
2297      <emphasis>now</emphasis>.
2298     </para>
2299    </sect2>
2300    <sect2 id="zoom.sru.record.behavior">
2301     <title>SRU/Solr Protocol behavior</title>
2302     <para>
2303      The ZOOM driver for SRU/Solr treats records returned by a SRU/Solr server
2304      as if they where Z39.50 records with transfer syntax XML and
2305      no element set name or database name.
2306     </para>
2307    </sect2>
2308   </sect1>
2309   <sect1 id="zoom.facets"><title>Facets</title>
2310    <para>
2311     Facet operations is not part of the official ZOOM specification, but
2312     is an Index Data extension for YAZ-based Z39.50 targets,
2313     <ulink url="&url.solr;">Solr</ulink> and SRU 2.0 targets.
2314
2315     Facets may be requestd by the
2316      <link linkend="zoom.facets.option">facets</link> option before a
2317     search is sent.
2318     For inspection of the returned facets, the following functions are
2319     available:
2320    </para>
2321    <synopsis>
2322     ZOOM_facet_field *ZOOM_resultset_facets(ZOOM_resultset r);
2323
2324     ZOOM_facet_field ZOOM_resultset_get_facet_field(ZOOM_resultset r,
2325                                                     const char *facet_name);
2326
2327     ZOOM_facet_field ZOOM_resultset_get_facet_field_by_index(ZOOM_resultset r,
2328                                                              int pos);
2329
2330     size_t ZOOM_resultset_facets_size(ZOOM_resultset r);
2331
2332     const char *ZOOM_facet_field_name(ZOOM_facet_field facet_field);
2333
2334     size_t ZOOM_facet_field_term_count(ZOOM_facet_field facet_field);
2335
2336     const char *ZOOM_facet_field_get_term(ZOOM_facet_field facet_field,
2337                                           size_t idx, int *freq);
2338    </synopsis>
2339    <para>
2340     References to temporary structures are returned by all functions.
2341     They are only valid as long the Result set is valid.
2342     <function>ZOOM_resultset_get_facet_field</function> or
2343     <function>ZOOM_resultset_get_facet_field_by_index</function>.
2344     <function>ZOOM_resultset_facets</function>.
2345     <function>ZOOM_facet_field_name</function>.
2346     <function>ZOOM_facet_field_get_term</function>.
2347     </para>
2348    <para id="zoom.resultset.get_facet_field">
2349     A single Facet field  is returned by function
2350     <function>ZOOM_resultset_get_facet_field</function> or
2351     <function>ZOOM_resultset_get_facet_field_by_index</function> that takes
2352     a  result set and facet name or positive index respectively. First
2353     facet has position zero. If no facet could be obtained (invalid name
2354     or index out of bounds) <literal>NULL</literal> is returned.
2355    </para>
2356    <para id="zoom.resultset.facets">
2357     An array of facets field can be returned by
2358     <function>ZOOM_resultset_facets</function>. The length of the array is
2359     given by <function>ZOOM_resultset_facets_size</function>. The array is
2360     zero-based and the last entry will be at
2361     <function>ZOOM_resultset_facets_size(result_set)</function>-1.
2362    </para>
2363    <para id="zoom.resultset.facets_names">
2364     It is possible to interate over facets by name, by calling
2365     <function>ZOOM_resultset_facets_names</function>.
2366     This will return a const array of char * where each string can be used
2367     as parameter for <function>ZOOM_resultset_get_facet_field</function>.
2368    </para>
2369    <para>
2370    Function <function>ZOOM_facet_field_name</function> gets the request
2371     facet name from a returned facet field.
2372    </para>
2373    <para>
2374     Function <function>ZOOM_facet_field_get_term</function> returns the
2375     idx'th term and term count for a facet field.
2376     Idx must between 0 and
2377     <function>ZOOM_facet_field_term_count</function>-1, otherwise the
2378     returned reference will be <literal>NULL</literal>. On a valid idx, the
2379     value of the freq reference will be the term count.
2380     The <literal>freq</literal> parameter must be valid pointer to integer.
2381    </para>
2382    </sect1>
2383   <sect1 id="zoom.scan"><title>Scan</title>
2384    <para>
2385     This section describes an interface for Scan. Scan is not an
2386     official part of the ZOOM model yet. The result of a scan operation
2387     is the <literal>ZOOM_scanset</literal> which is a set of terms
2388     returned by a target.
2389    </para>
2390
2391    <para>
2392     The Scan interface is supported for both Z39.50, SRU and Solr.
2393    </para>
2394
2395    <synopsis>
2396     ZOOM_scanset ZOOM_connection_scan(ZOOM_connection c,
2397                                       const char *startpqf);
2398
2399     ZOOM_scanset ZOOM_connection_scan1(ZOOM_connection c,
2400                                        ZOOM_query q);
2401
2402     size_t ZOOM_scanset_size(ZOOM_scanset scan);
2403
2404     const char *ZOOM_scanset_term(ZOOM_scanset scan, size_t pos,
2405                                   size_t *occ, size_t *len);
2406
2407     const char *ZOOM_scanset_display_term(ZOOM_scanset scan, size_t pos,
2408                                           size_t *occ, size_t *len);
2409
2410     void ZOOM_scanset_destroy(ZOOM_scanset scan);
2411
2412     const char *ZOOM_scanset_option_get(ZOOM_scanset scan,
2413                                         const char *key);
2414
2415     void ZOOM_scanset_option_set(ZOOM_scanset scan, const char *key,
2416                                  const char *val);
2417     </synopsis>
2418    <para>
2419     The scan set is created by function
2420     <function>ZOOM_connection_scan</function> which performs a scan
2421     operation on the connection using the specified
2422     <parameter>startpqf</parameter>.
2423     If the operation was successful, the size of the scan set can be
2424     retrieved by a call to <function>ZOOM_scanset_size</function>.
2425     Like result sets, the items are numbered 0..size-1.
2426     To obtain information about a particular scan term, call function
2427     <function>ZOOM_scanset_term</function>. This function takes
2428     a scan set offset <literal>pos</literal> and returns a pointer
2429     to a <emphasis>raw term</emphasis> or <literal>NULL</literal> if
2430     non-present.
2431     If present, the <literal>occ</literal> and <literal>len</literal>
2432     are set to the number of occurrences and the length
2433     of the actual term respectively.
2434     <function>ZOOM_scanset_display_term</function> is similar to
2435     <function>ZOOM_scanset_term</function> except that it returns
2436     the <emphasis>display term</emphasis> rather than the raw term.
2437     In a few cases, the term is different from display term. Always
2438     use the display term for display and the raw term for subsequent
2439     scan operations (to get more terms, next scan result, etc).
2440    </para>
2441    <para>
2442     A scan set may be freed by a call to function
2443     <function>ZOOM_scanset_destroy</function>.
2444     Functions <function>ZOOM_scanset_option_get</function> and
2445     <function>ZOOM_scanset_option_set</function> retrieves and sets
2446     an option respectively.
2447    </para>
2448    <para>
2449     The <parameter>startpqf</parameter> is a subset of PQF, namely
2450     the Attributes+Term part. Multiple <literal>@attr</literal> can
2451     be used. For example to scan in title (complete) phrases:
2452     <literallayout>
2453      @attr 1=4 @attr 6=2 "science o"
2454     </literallayout>
2455    </para>
2456    <para>
2457     The <function>ZOOM_connecton_scan1</function> is a newer and
2458     more generic alternative to <function>ZOOM_connection_scan</function>
2459     which allows to use both CQL and PQF for Scan.
2460    </para>
2461    <table frame="top" id="zoom.scanset.options">
2462     <title>ZOOM Scan Set Options</title>
2463     <tgroup cols="3">
2464      <colspec colwidth="4*" colname="name"></colspec>
2465      <colspec colwidth="7*" colname="description"></colspec>
2466      <colspec colwidth="2*" colname="default"></colspec>
2467      <thead>
2468       <row>
2469        <entry>Option</entry>
2470        <entry>Description</entry>
2471        <entry>Default</entry>
2472       </row>
2473      </thead>
2474      <tbody>
2475       <row><entry>
2476         number</entry><entry>Number of Scan Terms requested in next scan.
2477         After scan it holds the actual number of terms returned.
2478        </entry><entry>20</entry></row>
2479       <row><entry>
2480         position</entry><entry>Preferred Position of term in response
2481         in next scan; actual position after completion of scan.
2482        </entry><entry>1</entry></row>
2483       <row><entry>
2484         stepSize</entry><entry>Step Size
2485        </entry><entry>0</entry></row>
2486       <row><entry>
2487         scanStatus</entry><entry>An integer indicating the Scan Status
2488         of last scan.
2489        </entry><entry>0</entry></row>
2490       <row><entry>
2491         rpnCharset</entry><entry>Character set for RPN terms.
2492         If this is set, ZOOM C will assume that the ZOOM application is
2493         running UTF-8. Terms in RPN queries are then converted to the
2494         rpnCharset. If this is unset, ZOOM C will not assume any encoding
2495         of RPN terms and no conversion is performed.
2496        </entry><entry>none</entry></row>
2497      </tbody>
2498     </tgroup>
2499    </table>
2500   </sect1>
2501   <sect1 id="zoom.extendedservices">
2502    <title>Extended Services</title>
2503    <para>
2504     ZOOM offers an interface to a subset of the Z39.50 extended services
2505     as well as a few privately defined ones:
2506    </para>
2507    <itemizedlist>
2508     <listitem>
2509      <para>
2510       Z39.50 Item Order (ILL).
2511       See <xref linkend="zoom.item.order"/>.
2512      </para>
2513     </listitem>
2514     <listitem>
2515      <para>
2516       Record Update. This allows a client to insert, modify or delete
2517       records.
2518       See <xref linkend="zoom.record.update"/>.
2519      </para>
2520     </listitem>
2521     <listitem>
2522      <para>
2523       Database Create. This a non-standard feature. Allows a client
2524       to create a database.
2525       See <xref linkend="zoom.database.create"/>.
2526      </para>
2527     </listitem>
2528     <listitem>
2529      <para>
2530       Database Drop. This a non-standard feature. Allows a client
2531       to delete/drop a database.
2532       See <xref linkend="zoom.database.drop"/>.
2533      </para>
2534      </listitem>
2535     <listitem>
2536      <para>
2537       Commit operation. This a non-standard feature. Allows a client
2538       to commit operations.
2539       See <xref linkend="zoom.commit"/>.
2540      </para>
2541     </listitem>
2542     <!-- all the ILL PDU options should go here too -->
2543    </itemizedlist>
2544    <para>
2545     To create an extended service operation, a <literal>ZOOM_package</literal>
2546     must be created. The operation is a five step operation. The
2547     package is created, package is configured by means of options,
2548     the package is sent, result is inspected (by means of options),
2549     the package is destroyed.
2550    </para>
2551    <synopsis>
2552     ZOOM_package ZOOM_connection_package(ZOOM_connection c,
2553                                          ZOOM_options options);
2554
2555     const char *ZOOM_package_option_get(ZOOM_package p,
2556                                         const char *key);
2557     void ZOOM_package_option_set(ZOOM_package p, const char *key,
2558                                  const char *val);
2559     void ZOOM_package_send(ZOOM_package p, const char *type);
2560
2561     void ZOOM_package_destroy(ZOOM_package p);
2562    </synopsis>
2563    <para>
2564     The <function>ZOOM_connection_package</function> creates a
2565     package for the connection given using the options specified.
2566    </para>
2567    <para>
2568     Functions <function>ZOOM_package_option_get</function> and
2569     <function>ZOOM_package_option_set</function> gets and sets
2570     options.
2571    </para>
2572    <para>
2573     <function>ZOOM_package_send</function> sends
2574     the package the via connection specified in
2575     <function>ZOOM_connection_package</function>.
2576     The <parameter>type</parameter> specifies the actual extended service
2577     package type to be sent.
2578    </para>
2579    <table frame="top" id="zoom.extendedservices.type">
2580     <title>Extended Service Type</title>
2581     <tgroup cols="2">
2582      <colspec colwidth="3*" colname="value"></colspec>
2583      <colspec colwidth="7*" colname="description"></colspec>
2584      <thead>
2585       <row>
2586        <entry>Type</entry>
2587        <entry>Description</entry>
2588       </row>
2589      </thead>
2590      <tbody>
2591       <row>
2592        <entry>itemorder</entry><entry>Item Order</entry>
2593       </row>
2594       <row>
2595        <entry>update</entry><entry>Record Update</entry>
2596       </row>
2597       <row>
2598        <entry>create</entry><entry>Database Create</entry>
2599       </row>
2600       <row>
2601        <entry>drop</entry><entry>Database Drop</entry>
2602       </row>
2603       <row>
2604        <entry>commit</entry><entry>Commit Operation</entry>
2605       </row>
2606      </tbody>
2607     </tgroup>
2608    </table>
2609
2610    <table frame="top" id="zoom.extendedservices.options">
2611     <title>Extended Service Common Options</title>
2612     <tgroup cols="3">
2613      <colspec colwidth="4*" colname="name"></colspec>
2614      <colspec colwidth="7*" colname="description"></colspec>
2615      <colspec colwidth="3*" colname="default"></colspec>
2616      <thead>
2617       <row>
2618        <entry>Option</entry>
2619        <entry>Description</entry>
2620        <entry>Default</entry>
2621       </row>
2622      </thead>
2623      <tbody>
2624       <row>
2625        <entry>package-name</entry>
2626        <entry>Extended Service Request package name. Must be specified
2627        as part of a request.</entry>
2628        <entry>none</entry>
2629       </row>
2630       <row>
2631        <entry>user-id</entry>
2632        <entry>User ID of Extended Service Package. Is a request option.</entry>
2633        <entry>none</entry>
2634       </row>
2635       <row>
2636        <entry>function</entry>
2637        <entry>
2638         Function of package - one of <literal>create</literal>,
2639         <literal>delete</literal>, <literal>modify</literal>. Is
2640         a request option.
2641        </entry>
2642        <entry><literal>create</literal></entry>
2643       </row>
2644       <row>
2645        <entry>waitAction</entry>
2646        <entry>
2647         Wait action for package. Possible values:
2648         <literal>wait</literal>, <literal>waitIfPossible</literal>,
2649         <literal>dontWait</literal> or <literal>dontReturnPackage</literal>.
2650        </entry>
2651        <entry><literal>waitIfPossible</literal></entry>
2652       </row>
2653       <row>
2654        <entry>targetReference</entry>
2655        <entry>
2656         Target Reference. This is part of the response as returned
2657         by the server. Read it after a successful operation.
2658        </entry>
2659        <entry><literal>none</literal></entry>
2660       </row>
2661      </tbody>
2662     </tgroup>
2663    </table>
2664    <sect2 id="zoom.item.order">
2665     <title>Item Order</title>
2666     <para>
2667      For Item Order, <literal>type</literal> must be set to
2668      <literal>itemorder</literal> in
2669      <function>ZOOM_package_send</function>.
2670     </para>
2671
2672     <table frame="top" id="zoom.item.order.options">
2673      <title>Item Order Options</title>
2674      <tgroup cols="3">
2675       <colspec colwidth="4*" colname="name"></colspec>
2676       <colspec colwidth="7*" colname="description"></colspec>
2677       <colspec colwidth="3*" colname="default"></colspec>
2678       <thead>
2679        <row>
2680         <entry>Option</entry>
2681         <entry>Description</entry>
2682         <entry>Default</entry>
2683        </row>
2684       </thead>
2685       <tbody>
2686        <row>
2687         <entry>contact-name</entry>
2688         <entry>ILL contact name</entry>
2689         <entry>none</entry>
2690        </row>
2691        <row>
2692         <entry>contact-phone</entry>
2693         <entry>ILL contact phone</entry>
2694         <entry>none</entry>
2695        </row>
2696        <row>
2697         <entry>contact-email</entry>
2698         <entry>ILL contact email</entry>
2699         <entry>none</entry>
2700        </row>
2701        <row>
2702         <entry>itemorder-setname</entry>
2703         <entry>Name of result set for record</entry>
2704         <entry>default</entry>
2705        </row>
2706        <row>
2707         <entry>itemorder-item</entry>
2708         <entry>Position for item (record) requested. An integer</entry>
2709         <entry>1</entry>
2710        </row>
2711       </tbody>
2712      </tgroup>
2713     </table>
2714     <para>
2715      There are two variants of item order: ILL-variant and
2716      XML document variant. In order to use the XML variant the setting
2717      <literal>doc</literal> must hold the XML item order document. If that
2718      setting is unset, the ILL-variant is used.
2719     </para>
2720
2721     <table frame="top" id="zoom.illrequest.options">
2722      <title>ILL Request Options</title>
2723      <tgroup cols="1">
2724       <colspec colwidth="4*" colname="name"></colspec>
2725       <thead>
2726        <row>
2727         <entry>Option</entry>
2728        </row>
2729       </thead>
2730       <tbody>
2731        <row><entry>protocol-version-num</entry></row>
2732        <row><entry>transaction-id,initial-requester-id,person-or-institution-symbol,person</entry></row>
2733        <row><entry>transaction-id,initial-requester-id,person-or-institution-symbol,institution</entry></row>
2734        <row><entry>transaction-id,initial-requester-id,name-of-person-or-institution,name-of-person</entry></row>
2735        <row><entry>transaction-id,initial-requester-id,name-of-person-or-institution,name-of-institution</entry></row>
2736        <row><entry>transaction-id,transaction-group-qualifier</entry></row>
2737        <row><entry>transaction-id,transaction-qualifier</entry></row>
2738        <row><entry>transaction-id,sub-transaction-qualifier</entry></row>
2739        <row><entry>service-date-time,this,date</entry></row>
2740        <row><entry>service-date-time,this,time</entry></row>
2741        <row><entry>service-date-time,original,date</entry></row>
2742        <row><entry>service-date-time,original,time</entry></row>
2743        <row><entry>requester-id,person-or-institution-symbol,person</entry></row>
2744        <row><entry>requester-id,person-or-institution-symbol,institution</entry></row>
2745        <row><entry>requester-id,name-of-person-or-institution,name-of-person</entry></row>
2746        <row><entry>requester-id,name-of-person-or-institution,name-of-institution</entry></row>
2747        <row><entry>responder-id,person-or-institution-symbol,person</entry></row>
2748        <row><entry>responder-id,person-or-institution-symbol,institution</entry></row>
2749        <row><entry>responder-id,name-of-person-or-institution,name-of-person</entry></row>
2750        <row><entry>responder-id,name-of-person-or-institution,name-of-institution</entry></row>
2751        <row><entry>transaction-type</entry></row>
2752        <row><entry>delivery-address,postal-address,name-of-person-or-institution,name-of-person</entry></row>
2753        <row><entry>delivery-address,postal-address,name-of-person-or-institution,name-of-institution</entry></row>
2754        <row><entry>delivery-address,postal-address,extended-postal-delivery-address</entry></row>
2755        <row><entry>delivery-address,postal-address,street-and-number</entry></row>
2756        <row><entry>delivery-address,postal-address,post-office-box</entry></row>
2757        <row><entry>delivery-address,postal-address,city</entry></row>
2758        <row><entry>delivery-address,postal-address,region</entry></row>
2759        <row><entry>delivery-address,postal-address,country</entry></row>
2760        <row><entry>delivery-address,postal-address,postal-code</entry></row>
2761        <row><entry>delivery-address,electronic-address,telecom-service-identifier</entry></row>
2762        <row><entry>delivery-address,electronic-address,telecom-service-addreess</entry></row>
2763        <row><entry>billing-address,postal-address,name-of-person-or-institution,name-of-person</entry></row>
2764        <row><entry>billing-address,postal-address,name-of-person-or-institution,name-of-institution</entry></row>
2765        <row><entry>billing-address,postal-address,extended-postal-delivery-address</entry></row>
2766        <row><entry>billing-address,postal-address,street-and-number</entry></row>
2767        <row><entry>billing-address,postal-address,post-office-box</entry></row>
2768        <row><entry>billing-address,postal-address,city</entry></row>
2769        <row><entry>billing-address,postal-address,region</entry></row>
2770        <row><entry>billing-address,postal-address,country</entry></row>
2771        <row><entry>billing-address,postal-address,postal-code</entry></row>
2772        <row><entry>billing-address,electronic-address,telecom-service-identifier</entry></row>
2773        <row><entry>billing-address,electronic-address,telecom-service-addreess</entry></row>
2774        <row><entry>ill-service-type</entry></row>
2775        <row><entry>requester-optional-messages,can-send-RECEIVED</entry></row>
2776        <row><entry>requester-optional-messages,can-send-RETURNED</entry></row>
2777        <row><entry>requester-optional-messages,requester-SHIPPED</entry></row>
2778        <row><entry>requester-optional-messages,requester-CHECKED-IN</entry></row>
2779        <row><entry>search-type,level-of-service</entry></row>
2780        <row><entry>search-type,need-before-date</entry></row>
2781        <row><entry>search-type,expiry-date</entry></row>
2782        <row><entry>search-type,expiry-flag</entry></row>
2783        <row><entry>place-on-hold</entry></row>
2784        <row><entry>client-id,client-name</entry></row>
2785        <row><entry>client-id,client-status</entry></row>
2786        <row><entry>client-id,client-identifier</entry></row>
2787        <row><entry>item-id,item-type</entry></row>
2788        <row><entry>item-id,call-number</entry></row>
2789        <row><entry>item-id,author</entry></row>
2790        <row><entry>item-id,title</entry></row>
2791        <row><entry>item-id,sub-title</entry></row>
2792        <row><entry>item-id,sponsoring-body</entry></row>
2793        <row><entry>item-id,place-of-publication</entry></row>
2794        <row><entry>item-id,publisher</entry></row>
2795        <row><entry>item-id,series-title-number</entry></row>
2796        <row><entry>item-id,volume-issue</entry></row>
2797        <row><entry>item-id,edition</entry></row>
2798        <row><entry>item-id,publication-date</entry></row>
2799        <row><entry>item-id,publication-date-of-component</entry></row>
2800        <row><entry>item-id,author-of-article</entry></row>
2801        <row><entry>item-id,title-of-article</entry></row>
2802        <row><entry>item-id,pagination</entry></row>
2803        <row><entry>item-id,ISBN</entry></row>
2804        <row><entry>item-id,ISSN</entry></row>
2805        <row><entry>item-id,additional-no-letters</entry></row>
2806        <row><entry>item-id,verification-reference-source</entry></row>
2807        <row><entry>copyright-complicance</entry></row>
2808        <row><entry>retry-flag</entry></row>
2809        <row><entry>forward-flag</entry></row>
2810        <row><entry>requester-note</entry></row>
2811        <row><entry>forward-note</entry></row>
2812       </tbody>
2813      </tgroup>
2814     </table>
2815    </sect2>
2816    <sect2 id="zoom.record.update">
2817     <title>Record Update</title>
2818     <para>
2819      For Record Update, <literal>type</literal> must be set to
2820      <literal>update</literal> in
2821      <function>ZOOM_package_send</function>.
2822     </para>
2823     <table frame="top" id="zoom.record.update.options">
2824      <title>Record Update Options</title>
2825      <tgroup cols="3">
2826       <colspec colwidth="4*" colname="name"></colspec>
2827       <colspec colwidth="7*" colname="description"></colspec>
2828       <colspec colwidth="3*" colname="default"></colspec>
2829       <thead>
2830        <row>
2831         <entry>Option</entry>
2832         <entry>Description</entry>
2833         <entry>Default</entry>
2834        </row>
2835       </thead>
2836       <tbody>
2837        <row>
2838         <entry>action</entry>
2839         <entry>
2840          The update action. One of
2841          <literal>specialUpdate</literal>,
2842          <literal>recordInsert</literal>,
2843          <literal>recordReplace</literal>,
2844          <literal>recordDelete</literal>,
2845          <literal>elementUpdate</literal>.
2846         </entry>
2847         <entry><literal>specialUpdate (recordInsert for updateVersion=1 which does not support specialUpdate)</literal></entry>
2848        </row>
2849        <row>
2850         <entry>recordIdOpaque</entry>
2851         <entry>Opaque Record ID</entry>
2852         <entry>none</entry>
2853        </row>
2854        <row>
2855         <entry>recordIdNumber</entry>
2856         <entry>Record ID number</entry>
2857         <entry>none</entry>
2858        </row>
2859        <row>
2860         <entry>record</entry>
2861         <entry>The record itself</entry>
2862         <entry>none</entry>
2863        </row>
2864        <row>
2865         <entry>recordOpaque</entry>
2866         <entry>Specifies an opaque record which is
2867           encoded as an ASN.1 ANY type with the OID as tiven by option
2868           <literal>syntax</literal> (see below).
2869           Option <literal>recordOpaque</literal> is an alternative
2870           to record - and <literal>record</literal> option (above) is
2871           ignored if recordOpaque is set. This option is only available in
2872           YAZ 3.0.35 and later, and is meant to facilitate Updates with
2873           servers from OCLC.
2874         </entry>
2875         <entry>none</entry>
2876        </row>
2877        <row>
2878         <entry>syntax</entry>
2879         <entry>The record syntax (transfer syntax). Is a string that
2880          is a known record syntax.
2881         </entry>
2882         <entry>no syntax</entry>
2883        </row>
2884        <row>
2885         <entry>databaseName</entry>
2886         <entry>Database from connection object</entry>
2887         <entry>Default</entry>
2888        </row>
2889        <row>
2890         <entry>correlationInfo.note</entry>
2891         <entry>Correlation Info Note (string)</entry>
2892         <entry>none</entry>
2893        </row>
2894        <row>
2895         <entry>correlationInfo.id</entry>
2896         <entry>Correlation Info ID (integer)</entry>
2897         <entry>none</entry>
2898        </row>
2899        <row>
2900         <entry>elementSetName</entry>
2901         <entry>Element Set for Record</entry>
2902         <entry>none</entry>
2903        </row>
2904        <row>
2905         <entry>updateVersion</entry>
2906         <entry>Record Update version which holds one of the values
2907          1, 2 or 3. Each version has a distinct OID:
2908          1.2.840.10003.9.5
2909          (<ulink url="&url.z39.50.extupdate1;">first version</ulink>) ,
2910          1.2.840.10003.9.5.1
2911          (second version) and
2912          1.2.840.10003.9.5.1.1
2913          (<ulink url="&url.z39.50.extupdate3;">third and
2914           newest version</ulink>).
2915         </entry>
2916         <entry>3</entry>
2917        </row>
2918       </tbody>
2919      </tgroup>
2920     </table>
2921
2922    </sect2>
2923
2924    <sect2 id="zoom.database.create"><title>Database Create</title>
2925     <para>
2926      For Database Create, <literal>type</literal> must be set to
2927      <literal>create</literal> in
2928      <function>ZOOM_package_send</function>.
2929     </para>
2930
2931     <table frame="top" id="zoom.database.create.options">
2932      <title>Database Create Options</title>
2933      <tgroup cols="3">
2934       <colspec colwidth="4*" colname="name"></colspec>
2935       <colspec colwidth="7*" colname="description"></colspec>
2936       <colspec colwidth="3*" colname="default"></colspec>
2937       <thead>
2938        <row>
2939         <entry>Option</entry>
2940         <entry>Description</entry>
2941         <entry>Default</entry>
2942        </row>
2943       </thead>
2944       <tbody>
2945        <row>
2946         <entry>databaseName</entry>
2947         <entry>Database from connection object</entry>
2948         <entry>Default</entry>
2949        </row>
2950       </tbody>
2951      </tgroup>
2952     </table>
2953    </sect2>
2954    <sect2 id="zoom.database.drop">
2955     <title>Database Drop</title>
2956     <para>
2957      For Database Drop, <literal>type</literal> must be set to
2958      <literal>drop</literal> in
2959      <function>ZOOM_package_send</function>.
2960     </para>
2961     <table frame="top" id="zoom.database.drop.options">
2962      <title>Database Drop Options</title>
2963      <tgroup cols="3">
2964       <colspec colwidth="4*" colname="name"></colspec>
2965       <colspec colwidth="7*" colname="description"></colspec>
2966       <colspec colwidth="3*" colname="default"></colspec>
2967       <thead>
2968        <row>
2969         <entry>Option</entry>
2970         <entry>Description</entry>
2971         <entry>Default</entry>
2972        </row>
2973       </thead>
2974       <tbody>
2975        <row>
2976         <entry>databaseName</entry>
2977         <entry>Database from connection object</entry>
2978         <entry>Default</entry>
2979        </row>
2980       </tbody>
2981      </tgroup>
2982     </table>
2983    </sect2>
2984    <sect2 id="zoom.commit">
2985     <title>Commit Operation</title>
2986     <para>
2987      For Commit, <literal>type</literal> must be set to
2988      <literal>commit</literal> in
2989      <function>ZOOM_package_send</function>.
2990     </para>
2991    </sect2>
2992    <sect2 id="zoom.extended.services.behavior">
2993     <title>Protocol behavior</title>
2994     <para>
2995      All the extended services are Z39.50-only.
2996     </para>
2997     <note>
2998      <para>
2999       The database create, drop, and commit services are privately defined
3000       operations.
3001       Refer to <filename>esadmin.asn</filename> in YAZ for the ASN.1
3002       definitions.
3003      </para>
3004     </note>
3005    </sect2>
3006   </sect1>
3007   <sect1 id="zoom.options">
3008    <title>Options</title>
3009    <para>
3010     Most &zoom; objects provide a way to specify options to change behavior.
3011     From an implementation point of view, a set of options is just like
3012     an associative array / hash.
3013    </para>
3014    <synopsis>
3015      ZOOM_options ZOOM_options_create(void);
3016
3017      ZOOM_options ZOOM_options_create_with_parent(ZOOM_options parent);
3018
3019      void ZOOM_options_destroy(ZOOM_options opt);
3020    </synopsis>
3021    <synopsis>
3022      const char *ZOOM_options_get(ZOOM_options opt, const char *name);
3023
3024      void ZOOM_options_set(ZOOM_options opt, const char *name,
3025                            const char *v);
3026    </synopsis>
3027    <synopsis>
3028      typedef const char *(*ZOOM_options_callback)
3029                             (void *handle, const char *name);
3030
3031      ZOOM_options_callback
3032              ZOOM_options_set_callback(ZOOM_options opt,
3033                                        ZOOM_options_callback c,
3034                                        void *handle);
3035    </synopsis>
3036   </sect1>
3037   <sect1 id="zoom.queryconversions">
3038    <title>Query conversions</title>
3039    <synopsis>
3040     int ZOOM_query_cql2rpn(ZOOM_query s, const char *cql_str,
3041                            ZOOM_connection conn);
3042
3043     int ZOOM_query_ccl2rpn(ZOOM_query s, const char *ccl_str,
3044                            const char *config,
3045                            int *ccl_error, const char **error_string,
3046                            int *error_pos);
3047    </synopsis>
3048    <para>
3049     <function>ZOOM_query_cql2rpn</function> translates the CQL string,
3050     client-side, into RPN which may be passed to the server.
3051     This is useful for servers that don't themselves
3052     support CQL, for which <function>ZOOM_query_cql</function> is useless.
3053     `conn' is used  only as a place to stash diagnostics if compilation
3054     fails; if this information is not needed, a null pointer may be used.
3055     The CQL conversion is driven by option <literal>cqlfile</literal> from
3056     connection conn. This specifies a conversion file (e.g. pqf.properties)
3057     which <emphasis>must</emphasis> be present.
3058    </para>
3059    <para>
3060     <function>ZOOM_query_ccl2rpn</function> translates the CCL string,
3061     client-side, into RPN which may be passed to the server.
3062     The conversion is driven by the specification given by
3063     <literal>config</literal>. Upon completion 0 is returned on success; -1
3064     is returned on failure. On failure <literal>error_string</literal> and
3065     <literal>error_pos</literal> hold the error message and position of
3066     first error in original CCL string.
3067    </para>
3068   </sect1>
3069   <sect1 id="zoom.events"><title>Events</title>
3070    <para>
3071     If you're developing non-blocking applications, you have to deal
3072     with events.
3073    </para>
3074    <synopsis>
3075     int ZOOM_event(int no, ZOOM_connection *cs);
3076    </synopsis>
3077    <para>
3078     The <function>ZOOM_event</function> executes pending events for
3079     a number of connections. Supply the number of connections in
3080     <literal>no</literal> and an array of connections in
3081     <literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
3082     A pending event could be sending a search, receiving a response,
3083     etc.
3084     When an event has occurred for one of the connections, this function
3085     returns a positive integer <literal>n</literal> denoting that an event
3086     occurred for connection <literal>cs[n-1]</literal>.
3087     When no events are pending for the connections, a value of zero is
3088     returned.
3089     To ensure that all outstanding requests are performed, call this function
3090     repeatedly until zero is returned.
3091    </para>
3092    <para>
3093     If <function>ZOOM_event</function> returns, and returns non-zero, the
3094     last event that occurred can be expected.
3095    </para>
3096    <synopsis>
3097     int ZOOM_connection_last_event(ZOOM_connection cs);
3098    </synopsis>
3099    <para>
3100     <function>ZOOM_connection_last_event</function> returns an event type
3101     (integer) for the last event.
3102    </para>
3103
3104    <table frame="top" id="zoom.event.ids">
3105     <title>ZOOM Event IDs</title>
3106     <tgroup cols="2">
3107      <colspec colwidth="4*" colname="name"></colspec>
3108      <colspec colwidth="7*" colname="description"></colspec>
3109      <thead>
3110       <row>
3111        <entry>Event</entry>
3112        <entry>Description</entry>
3113       </row>
3114      </thead>
3115      <tbody>
3116       <row>
3117        <entry>ZOOM_EVENT_NONE</entry>
3118        <entry>No event has occurred</entry>
3119       </row>
3120       <row>
3121        <entry>ZOOM_EVENT_CONNECT</entry>
3122        <entry>TCP/IP connect has initiated</entry>
3123       </row>
3124       <row>
3125        <entry>ZOOM_EVENT_SEND_DATA</entry>
3126        <entry>Data has been transmitted (sending)</entry>
3127       </row>
3128       <row>
3129        <entry>ZOOM_EVENT_RECV_DATA</entry>
3130        <entry>Data has been received</entry>
3131       </row>
3132       <row>
3133        <entry>ZOOM_EVENT_TIMEOUT</entry>
3134        <entry>Timeout</entry>
3135       </row>
3136       <row>
3137        <entry>ZOOM_EVENT_UNKNOWN</entry>
3138        <entry>Unknown event</entry>
3139       </row>
3140       <row>
3141        <entry>ZOOM_EVENT_SEND_APDU</entry>
3142        <entry>An APDU has been transmitted (sending)</entry>
3143       </row>
3144       <row>
3145        <entry>ZOOM_EVENT_RECV_APDU</entry>
3146        <entry>An APDU has been received</entry>
3147       </row>
3148       <row>
3149        <entry>ZOOM_EVENT_RECV_RECORD</entry>
3150        <entry>A result-set record has been received</entry>
3151       </row>
3152       <row>
3153        <entry>ZOOM_EVENT_RECV_SEARCH</entry>
3154        <entry>A search result has been received</entry>
3155       </row>
3156      </tbody>
3157     </tgroup>
3158    </table>
3159   </sect1>
3160  </chapter>
3161  <chapter id="server">
3162   <title>Generic server</title>
3163   <sect1 id="server.introduction"><title>Introduction</title>
3164    <para>
3165     If you aren't into documentation, a good way to learn how the
3166     back end interface works is to look at the <filename>backend.h</filename>
3167     file. Then, look at the small dummy-server in
3168     <filename>ztest/ztest.c</filename>. The <filename>backend.h</filename>
3169     file also makes a good reference, once you've chewed your way through
3170     the prose of this file.
3171    </para>
3172    <para>
3173     If you have a database system that you would like to make available by
3174     means of Z39.50 or SRU, &yaz; basically offers your two options. You
3175     can use the APIs provided by the &asn;, &odr;, and &comstack;
3176     modules to
3177     create and decode PDUs, and exchange them with a client.
3178     Using this low-level interface gives you access to all fields and
3179     options of the protocol, and you can construct your server as close
3180     to your existing database as you like.
3181     It is also a fairly involved process, requiring
3182     you to set up an event-handling mechanism, protocol state machine,
3183     etc. To simplify server implementation, we have implemented a compact
3184     and simple, but reasonably full-functioned server-frontend that will
3185     handle most of the protocol mechanics, while leaving you to
3186     concentrate on your database interface.
3187    </para>
3188    <note>
3189     <para>
3190      The backend interface was designed in anticipation of a specific
3191      integration task, while still attempting to achieve some degree of
3192      generality. We realize fully that there are points where the
3193      interface can be improved significantly. If you have specific
3194      functions or parameters that you think could be useful, send us a
3195      mail (or better, sign on to the mailing list referred to in the
3196      top-level README file). We will try to fit good suggestions into future
3197      releases, to the extent that it can be done without requiring
3198      too many structural changes in existing applications.
3199     </para>
3200    </note>
3201    <note>
3202     <para>
3203      The &yaz; server does not support XCQL.
3204      </para>
3205    </note>
3206   </sect1>
3207   <sect1 id="server.frontend">
3208    <title>The Database Frontend</title>
3209    <para>
3210     We refer to this software as a generic database frontend. Your
3211     database system is the <emphasis>backend database</emphasis>, and the
3212     interface between the two is called the <emphasis>backend API</emphasis>.
3213     The backend API consists of a small number of function handlers and
3214     structure definitions. You are required to provide the
3215     <function>main()</function> routine for the server (which can be
3216     quite simple), as well as a set of handlers to match each of the
3217     prototypes.
3218     The interface functions that you write can use any mechanism you like
3219     to communicate with your database system: You might link the whole
3220     thing together with your database application and access it by
3221     function calls; you might use IPC to talk to a database server
3222     somewhere; or you might link with third-party software that handles
3223     the communication for you (like a commercial database client library).
3224     At any rate, the handlers will perform the tasks of:
3225    </para>
3226    <itemizedlist>
3227     <listitem><para>
3228      Initialization.
3229     </para></listitem>
3230     <listitem><para>
3231      Searching.
3232     </para></listitem>
3233     <listitem><para>
3234      Fetching records.
3235     </para></listitem>
3236     <listitem><para>
3237      Scanning the database index (optional - if you wish to implement SCAN).
3238     </para></listitem>
3239     <listitem><para>
3240      Extended Services (optional).
3241     </para></listitem>
3242     <listitem><para>
3243      Result-Set Delete (optional).
3244     </para></listitem>
3245     <listitem><para>
3246      Result-Set Sort (optional).
3247     </para></listitem>
3248     <listitem><para>
3249      Return Explain for SRU (optional).
3250     </para></listitem>
3251    </itemizedlist>
3252    <para>
3253     (more functions will be added in time to support as much of
3254     Z39.50-1995 as possible).
3255    </para>
3256   </sect1>
3257   <sect1 id="server.backend">
3258    <title>The Backend API</title>
3259    <para>
3260     The header file that you need to use the interface are in the
3261     <filename>include/yaz</filename> directory. It's called
3262     <filename>backend.h</filename>. It will include other files from
3263     the <filename>include/yaz</filename> directory, so you'll
3264     probably want to use the -I option of your compiler to tell it
3265     where to find the files. When you run
3266     <literal>make</literal> in the top-level &yaz; directory,
3267     everything you need to create your server is to link with the
3268     <filename>lib/libyaz.la</filename> library.
3269    </para>
3270   </sect1>
3271   <sect1 id="server.main">
3272    <title>Your main() Routine</title>
3273    <para>
3274     As mentioned, your <function>main()</function> routine can be quite brief.
3275     If you want to initialize global parameters, or read global configuration
3276     tables, this is the place to do it. At the end of the routine, you should
3277     call the function
3278    </para>
3279    <synopsis>
3280 int statserv_main(int argc, char **argv,
3281                   bend_initresult *(*bend_init)(bend_initrequest *r),
3282                   void (*bend_close)(void *handle));
3283    </synopsis>
3284    <para>
3285     The third and fourth arguments are pointers to handlers. Handler
3286     <function>bend_init</function> is called whenever the server receives
3287     an Initialize Request, so it serves as a Z39.50 session initializer. The
3288     <function>bend_close</function> handler is called when the session is
3289     closed.
3290    </para>
3291    <para>
3292     <function>statserv_main</function> will establish listening sockets
3293     according to the parameters given. When connection requests are received,
3294     the event handler will typically <function>fork()</function> and
3295     create a sub-process to handle a new connection.
3296     Alternatively the server may be setup to create threads for each
3297     connection.
3298     If you do use global variables and forking, you should be aware, then,
3299     that these cannot be shared between associations, unless you explicitly
3300     disable forking by command line parameters.
3301    </para>
3302    <para>
3303     The server provides a mechanism for controlling some of its behavior
3304     without using command-line options. The function
3305    </para>
3306    <synopsis>
3307     statserv_options_block *statserv_getcontrol(void);
3308    </synopsis>
3309    <para>
3310     will return a pointer to a <literal>struct statserv_options_block</literal>
3311     describing the current default settings of the server. The structure
3312     contains these elements:
3313     <variablelist>
3314      <varlistentry>
3315       <term><literal>int dynamic</literal></term>
3316       <listitem><para>
3317        A boolean value, which determines whether the server
3318        will fork on each incoming request (TRUE), or not (FALSE). Default is
3319        TRUE. This flag is only read by UNIX-based servers (WIN32 based servers
3320        doesn't fork).
3321      </para></listitem>
3322      </varlistentry>
3323      <varlistentry>
3324       <term><literal>int threads</literal></term>
3325       <listitem><para>
3326        A boolean value, which determines whether the server
3327        will create a thread on each incoming request (TRUE), or not (FALSE).
3328        Default is FALSE. This flag is only read by UNIX-based servers
3329        that offer POSIX Threads support.
3330        WIN32-based servers always operate in threaded mode.
3331      </para></listitem>
3332      </varlistentry>
3333      <varlistentry>
3334       <term><literal>int inetd</literal></term>
3335       <listitem><para>
3336        A boolean value, which determines whether the server
3337        will operates under a UNIX INET daemon (inetd). Default is FALSE.
3338      </para></listitem>
3339      </varlistentry>
3340      <varlistentry>
3341       <term><literal>char logfile[ODR_MAXNAME+1]</literal></term>
3342       <listitem><para>File for diagnostic output (&quot;&quot;: stderr).
3343      </para></listitem>
3344      </varlistentry>
3345      <varlistentry>
3346       <term><literal>char apdufile[ODR_MAXNAME+1]</literal></term>
3347       <listitem><para>
3348        Name of file for logging incoming and outgoing APDUs
3349        (&quot;&quot;: don't log APDUs, &quot;-&quot;:
3350        <literal>stderr</literal>).
3351      </para></listitem>
3352      </varlistentry>
3353      <varlistentry>
3354       <term><literal>char default_listen[1024]</literal></term>
3355       <listitem><para>Same form as the command-line specification of
3356       listener address. &quot;&quot;: no default listener address.
3357       Default is to listen at &quot;tcp:@:9999&quot;. You can only
3358       specify one default listener address in this fashion.
3359      </para></listitem>
3360      </varlistentry>
3361      <varlistentry>
3362       <term><literal>enum oid_proto default_proto;</literal></term>
3363       <listitem><para>Either <literal>PROTO_Z3950</literal> or
3364       <literal>PROTO_SR</literal>.
3365       Default is <literal>PROTO_Z39_50</literal>.
3366      </para></listitem>
3367      </varlistentry>
3368      <varlistentry>
3369       <term><literal>int idle_timeout;</literal></term>
3370       <listitem><para>Maximum session idle-time, in minutes. Zero indicates
3371       no (infinite) timeout. Default is 15 minutes.
3372      </para></listitem>
3373      </varlistentry>
3374      <varlistentry>
3375       <term><literal>int maxrecordsize;</literal></term>
3376       <listitem><para>Maximum permissible record (message) size. Default
3377       is 64 MB. This amount of memory will only be allocated if a
3378       client requests a very large amount of records in one operation
3379       (or a big record).
3380       Set it to a lower number if you are worried about resource
3381       consumption on your host system.
3382      </para></listitem>
3383      </varlistentry>
3384      <varlistentry>
3385       <term><literal>char configname[ODR_MAXNAME+1]</literal></term>
3386       <listitem><para>Passed to the backend when a new connection is received.
3387      </para></listitem>
3388      </varlistentry>
3389      <varlistentry>
3390       <term><literal>char setuid[ODR_MAXNAME+1]</literal></term>
3391       <listitem><para>Set user id to the user specified, after binding
3392       the listener addresses.
3393      </para></listitem>
3394      </varlistentry>
3395      <varlistentry>
3396       <term>
3397        <literal>void (*bend_start)(struct statserv_options_block *p)</literal>
3398       </term>
3399       <listitem><para>Pointer to function which is called after the
3400       command line options have been parsed - but before the server
3401       starts listening.
3402       For forked UNIX servers this handler is called in the mother
3403       process; for threaded servers this handler is called in the
3404       main thread.
3405       The default value of this pointer is NULL in which case it
3406       isn't invoked by the frontend server.
3407       When the server operates as an NT service this handler is called
3408       whenever the service is started.
3409       </para></listitem>
3410      </varlistentry>
3411      <varlistentry>
3412       <term>
3413        <literal>void (*bend_stop)(struct statserv_options_block *p)</literal>
3414       </term>
3415       <listitem><para>Pointer to function which is called whenever the server
3416       has stopped listening for incoming connections. This function pointer
3417       has a default value of NULL in which case it isn't called.
3418       When the server operates as an NT service this handler is called
3419       whenever the service is stopped.
3420       </para></listitem>
3421      </varlistentry>
3422      <varlistentry>
3423       <term><literal>void *handle</literal></term>
3424       <listitem><para>User defined pointer (default value NULL).
3425       This is a per-server handle that can be used to specify "user-data".
3426       Do not confuse this with the session-handle as returned by bend_init.
3427       </para></listitem>
3428      </varlistentry>
3429     </variablelist>
3430    </para>
3431    <para>
3432     The pointer returned by <literal>statserv_getcontrol</literal> points to
3433     a static area. You are allowed to change the contents of the structure,
3434     but the changes will not take effect before you call
3435    </para>
3436    <synopsis>
3437 void statserv_setcontrol(statserv_options_block *block);
3438    </synopsis>
3439    <note>
3440     <para>
3441      that you should generally update this structure before calling
3442      <function>statserv_main()</function>.
3443     </para>
3444    </note>
3445   </sect1>
3446   <sect1 id="server.backendfunctions">
3447    <title>The Backend Functions</title>
3448    <para>
3449     For each service of the protocol, the backend interface declares one or
3450     two functions. You are required to provide implementations of the
3451     functions representing the services that you wish to implement.
3452    </para>
3453    <sect2 id="server.init">
3454     <title>Init</title>
3455     <synopsis>
3456 bend_initresult (*bend_init)(bend_initrequest *r);
3457     </synopsis>
3458     <para>
3459      This handler is called once for each new connection request, after
3460      a new process/thread has been created, and an Initialize Request has
3461      been received from the client. The pointer to the
3462      <function>bend_init</function> handler is passed in the call to
3463      <function>statserv_start</function>.
3464     </para>
3465     <para>
3466      This handler is also called when operating in SRU mode - when
3467      a connection has been made (even though SRU does not offer
3468      this service).
3469     </para>
3470     <para>
3471      Unlike previous versions of YAZ, the <function>bend_init</function> also
3472      serves as a handler that defines the Z39.50 services that the backend
3473      wish to support. Pointers to <emphasis>all</emphasis> service handlers,
3474      including search - and fetch must be specified here in this handler.
3475     </para>
3476     <para>
3477      The request - and result structures are defined as
3478     </para>
3479     <synopsis>
3480 typedef struct bend_initrequest
3481 {
3482     /** \brief user/name/password to be read */
3483     Z_IdAuthentication *auth;
3484     /** \brief encoding stream (for results) */