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