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