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