6b4c3f3d3aa4b7c25f9c456d75f74accdb360183
[yaz-moved-to-github.git] / doc / book.xml
1 <?xml version="1.0" standalone="no"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3     "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
4 [
5      <!ENTITY % local SYSTEM "local.ent">
6      %local;
7      <!ENTITY % entities SYSTEM "entities.ent">
8      %entities;
9      <!ENTITY % idcommon SYSTEM "common/common.ent">
10      %idcommon;
11 ]>
12 <book>
13  <bookinfo>
14   <title>YAZ User&apos;s Guide and Reference</title>
15   <authorgroup>
16    <author><firstname>Sebastian</firstname><surname>Hammer</surname></author>
17    <author><firstname>Adam</firstname><surname>Dickmeiss</surname></author>
18    <author><firstname>Mike</firstname><surname>Taylor</surname></author>
19    <author><firstname>Heikki</firstname><surname>Levanto</surname></author>
20    <author><firstname>Dennis</firstname><surname>Schafroth</surname></author>
21   </authorgroup>
22   <releaseinfo>&version;</releaseinfo>
23   <copyright>
24    <year>&copyright-year;</year>
25    <holder>Index Data</holder>
26   </copyright>
27   <abstract>
28    <simpara>
29     This document is the programmer's guide and reference to the &yaz;
30     package version &version;. &yaz; is a compact toolkit that provides
31     access to the Z39.50 and SRU/Solr protocols, as well as a set of
32     higher-level tools for implementing the server and client
33     roles, respectively.
34     The documentation can be used on its own, or as a reference when
35     looking at the example applications provided with the package.
36    </simpara>
37    <simpara>
38     <inlinemediaobject>
39      <imageobject>
40       <imagedata fileref="common/id.png" format="PNG"/>
41      </imageobject>
42      <imageobject>
43       <imagedata fileref="common/id.eps" format="EPS"/>
44      </imageobject>
45     </inlinemediaobject>
46    </simpara></abstract>
47  </bookinfo>
48  <chapter id="introduction">
49   <title>Introduction</title>
50   <para>
51    &yaz; is a C/C++ library for information retrieval applications
52    using the Z39.50/SRU/Solr protocols for information retrieval.
53   </para>
54   <para>
55    Properties of &yaz;:
56    <itemizedlist>
57     <listitem>
58      <para>
59       Complete
60       <ulink url="&url.z39.50;">Z39.50</ulink> version 3 support.
61       Amendments and Z39.50-2002 revision is supported.
62     </para>
63     </listitem>
64     <listitem>
65      <para>
66       Supports
67       <ulink url="&url.sru;">SRU GET/POST/SOAP</ulink>
68       version 1.1, 1.2 and 2.0 (over HTTP and HTTPS).
69     </para>
70     </listitem>
71     <listitem>
72      <para>
73       Includes BER encoders/decoders for the
74       <ulink url="&url.ill;">ISO ILL</ulink>
75       protocol.
76     </para>
77     </listitem>
78     <listitem>
79      <para>
80       Supports
81       <ulink url="&url.solr;">Apache Solr</ulink> Web Service version 1.4.x
82       (client side only)
83      </para>
84     </listitem>
85     <listitem>
86      <para>
87       Supports the following transports: BER over TCP/IP
88       (<ulink url="&url.ber.over.tcpip;">RFC1729</ulink>),
89       BER over unix local socket, and
90       <ulink url="&url.http.1.1;">HTTP 1.1</ulink>.
91     </para>
92     </listitem>
93     <listitem>
94      <para>
95       Secure Socket Layer support using
96       <ulink url="&url.gnutls;">GnuTLS</ulink>.
97       If enabled, &yaz; uses HTTPS transport (for SOAP) or
98       "Secure BER" (for Z39.50).
99      </para>
100     </listitem>
101     <listitem>
102      <para>
103       Offers
104       <ulink url="&url.zoom;">ZOOM</ulink> C API implementing
105       Z39.50, SRU and Solr Web Service.
106     </para>
107     </listitem>
108     <listitem>
109      <para>
110       The &yaz; library offers a set of useful utilities
111       related to the protocols, such as MARC (ISO2709) parser,
112       CCL (ISO8777) parser,
113       <ulink url="&url.cql;">CQL</ulink>
114       parser, memory management routines, character set conversion.
115      </para>
116     </listitem>
117     <listitem>
118      <para>
119       Portable code. &yaz; compiles out-of-the box on most Unixes and
120       on Windows using Microsoft Visual C++.
121      </para>
122     </listitem>
123     <listitem>
124      <para>
125       Fast operation. The C based BER encoders/decoders as well
126       as the server component of &yaz; is very fast.
127     </para>
128     </listitem>
129     <listitem>
130      <para>
131       Liberal license that allows for commercial use of &yaz;.
132      </para>
133     </listitem>
134    </itemizedlist>
135   </para>
136
137   <sect1 id="introduction.reading">
138    <title>Reading this Manual</title>
139    <para>
140     Most implementors only need to read a fraction of the
141     material in this manual, so a quick walkthrough of the chapters
142     is in order.
143    </para>
144    <itemizedlist>
145     <listitem>
146      <para>
147       <xref linkend="installation"/> contains installation
148       instructions for &yaz;. You don't need to read this
149       if you expect to download &yaz; binaries.
150       However, the chapter contains information about how
151       to make <emphasis>your</emphasis> application link
152       with &yaz;.
153      </para>
154     </listitem>
155     <listitem>
156      <para>
157       <xref linkend="zoom"/> describes the ZOOM API of &yaz;.
158       This is definitely worth reading if you wish to develop a Z39.50/SRU
159       client.
160      </para>
161     </listitem>
162     <listitem>
163      <para>
164       <xref linkend="server"/> describes the generic frontend server
165       and explains how to develop server Z39.50/SRU applications for &yaz;.
166       Obviously worth reading if you're to develop a server.
167     </para>
168     </listitem>
169     <listitem>
170      <para>
171       <xref linkend="yaz-client"/> describes how to use the &yaz; Z39.50
172       client. If you're a developer and wish to test your server
173       or a server from another party, you might find this chapter
174       useful.
175     </para>
176     </listitem>
177     <listitem>
178      <para>
179       <xref linkend="asn"/> documents the most commonly used Z39.50
180       C data structures offered by the &yaz; API. Client
181       developers using ZOOM and non-Z39.50 implementors may skip this.
182      </para>
183     </listitem>
184     <listitem>
185      <para>
186       <xref linkend="soap"/> describes how SRU and SOAP is used
187       in &yaz;. Only if you're developing SRU applications
188       this section is a must.
189      </para>
190     </listitem>
191     <listitem>
192      <para>
193       <xref linkend="tools"/> contains sections for the various
194       tools offered by &yaz;. Scan through the material quickly
195       and see what's relevant to you! SRU implementors
196       might find the <link linkend="cql">CQL</link> section
197       particularly useful.
198      </para>
199     </listitem>
200     <listitem>
201      <para>
202       <xref linkend="odr"/> goes through the details of the
203       ODR module which is the work horse that encodes and decodes
204       BER packages. Implementors using ZOOM only, do <emphasis>not</emphasis>
205       need to read this.
206       Most other Z39.50 implementors only need to read the first two
207       sections (<xref linkend="odr.introduction"/> and
208       <xref linkend="odr.use"/>).
209      </para>
210     </listitem>
211     <listitem>
212      <para>
213       <xref linkend="comstack"/> describes the network layer module
214       COMSTACK. Implementors using ZOOM or the generic frontend server
215       may skip this. Others, presumably, handling client/server
216      communication on their own should read this.
217      </para>
218     </listitem>
219    </itemizedlist>
220   </sect1>
221   <sect1 id="introduction.api">
222    <title>The API</title>
223    <para>
224     The <ulink url="&url.yaz;">&yaz;</ulink>
225     toolkit offers several different levels of access to the
226     <ulink url="&url.z39.50;">ISO23950/Z39.50</ulink>,
227     <ulink url="&url.ill;">ILL</ulink> and
228     <ulink url="&url.sru;">SRU</ulink>
229     protocols.
230     The level that you need to use depends on your requirements, and
231     the role (server or client) that you want to implement.
232     If you're developing a client application you should consider the
233     <link linkend="zoom">ZOOM</link> API.
234     It is, by far, the easiest way to develop clients in C.
235     Server implementers should consider the
236     <link linkend="server">generic frontend server</link>.
237     None of those high-level APIs support the whole protocol, but
238     they do include most facilities used in existing Z39.50 applications.
239    </para>
240    <para>
241     If you're using 'exotic' functionality (meaning anything not included in
242     the high-level APIs), developing non-standard extensions to Z39.50 or
243     you're going to develop an ILL application you'll have to learn the lower
244     level APIs of &yaz;.
245    </para>
246    <para>
247     The YAZ toolkit modules are shown in figure <xref linkend="yaz.layer"/>.
248    </para>
249    <figure id="yaz.layer">
250     <title>YAZ layers</title>
251     <mediaobject>
252      <imageobject>
253       <imagedata fileref="apilayer.png" format="PNG"/>
254      </imageobject>
255      <imageobject>
256       <imagedata fileref="apilayer.eps" format="EPS"/>
257      </imageobject>
258     </mediaobject>
259    </figure>
260    <para>
261     There are four layers.
262     <itemizedlist>
263      <listitem>
264       <para>A client or server application (or both).
265        This layer includes ZOOM and the generic frontend server.
266       </para>
267      </listitem>
268      <listitem>
269       <para>
270        The second layer provides a C represenation of the
271        protocol units (packages) for Z39.50 ASN.1, ILL ASN.1,
272        SRU.
273       </para>
274      </listitem>
275      <listitem>
276       <para>
277        The third layer encodes and decodes protocol data units to
278        simple packages (buffer with certain length). The &odr; module
279        encodes and decodes BER whereas the HTTP modules encodes and
280        decodes HTTP ruquests/responses.
281       </para>
282      </listitem>
283      <listitem>
284       <para>
285        The lowest layer is &comstack; which exchanges the encoded packages
286        with a peer process over a network.
287       </para>
288      </listitem>
289     </itemizedlist>
290    </para>
291    <para>
292     The &asn; module represents the ASN.1 definition of
293     the Z39.50 protocol. It establishes a set of type and
294     structure definitions, with one structure for each of the top-level
295     PDUs, and one structure or type for each of the contained ASN.1 types.
296     For primitive types, or other types that are defined by the ASN.1
297     standard itself (such as the EXTERNAL type), the C representation is
298     provided by the &odr; (Open Data Representation) subsystem.
299   </para>
300    <para>
301      &odr; is a basic mechanism for representing an
302     ASN.1 type in the C programming language, and for implementing BER
303     encoders and decoders for values of that type. The types defined in
304     the &asn; module generally have the prefix <literal>Z_</literal>, and
305     a suffix corresponding to the name of the type in the ASN.1
306     specification of the protocol (generally Z39.50-1995). In the case of
307     base types (those originating in the ASN.1 standard itself), the prefix
308     <literal>Odr_</literal> is sometimes seen. Either way, look for
309     the actual definition in either <filename>z-core.h</filename> (for the types
310     from the protocol), <filename>odr.h</filename> (for the primitive ASN.1
311     types).
312     The &asn; library also provides functions (which are, in turn,
313     defined using &odr; primitives) for encoding and decoding data values.
314     Their general form is
315     <funcsynopsis>
316      <funcprototype><funcdef>int <function>z_<replaceable>xxx</replaceable></function></funcdef>
317       <paramdef>ODR <parameter>o</parameter></paramdef>
318       <paramdef>Z_<replaceable>xxx</replaceable> **<parameter>p</parameter></paramdef>
319       <paramdef>int <parameter>optional</parameter></paramdef>
320       <paramdef>const char *<parameter>name</parameter></paramdef>
321      </funcprototype>
322     </funcsynopsis>
323     (note the lower-case &quot;z&quot; in the function name)
324    </para>
325    <note>
326     <para>
327      If you are using the premade definitions of the &asn; module, and you
328      are not adding a new protocol of your own, the only parts of &odr; that you
329      need to worry about are documented in
330      <xref linkend="odr.use"/>.
331     </para>
332    </note>
333    <para>
334     When you have created a BER-encoded buffer, you can use the &comstack;
335     subsystem to transmit (or receive) data over the network. The &comstack;
336     module provides simple functions for establishing a connection
337     (passively or actively, depending on the role of your application),
338     and for exchanging BER-encoded PDUs over that connection. When you
339     create a connection endpoint, you need to specify what transport to
340     use (TCP/IP, SSL or UNIX sockets).
341     For the remainder of the connection's lifetime, you don't have
342     to worry about the underlying transport protocol at all - the &comstack;
343     will ensure that the correct mechanism is used.
344    </para>
345    <para>
346     We call the combined interfaces to &odr;, &asn;, and &comstack; the service
347     level API. It's the API that most closely models the Z39.50
348     service/protocol definition, and it provides unlimited access to all
349     fields and facilities of the protocol definitions.
350    </para>
351    <para>
352     The reason that the &yaz; service-level API is a conglomerate of the
353     APIs from three different submodules is twofold. First, we wanted to allow
354     the user a choice of different options for each major task. For instance,
355     if you don't like the protocol API provided by &odr;/&asn;, you
356     can use SNACC or BERUtils instead, and still have the benefits of the
357     transparent transport approach of the &comstack; module. Secondly,
358     we realize that you may have to fit the toolkit into an existing
359     event-processing structure, in a way that is incompatible with
360     the &comstack; interface or some other part of &yaz;.
361    </para>
362   </sect1>
363  </chapter>
364  <chapter id="installation">
365   <title>Compilation and Installation</title>
366   <sect1 id="installation-introduction">
367    <title>Introduction</title>
368    <para>
369     The latest version of the software will generally be found at:
370    </para>
371    <para>
372     <ulink url="&url.yaz.download;"/>
373    </para>
374    <para>
375     We have tried our best to keep the software portable, and on many
376     platforms, you should be able to compile everything with little or
377     no changes.
378    </para>
379    <para>
380     The software is regularly tested on
381     <ulink url="&url.debian;">Debian GNU/Linux</ulink>,
382     <ulink url="&url.centos;">CentOS</ulink>,
383     <ulink url="&url.ubuntu;">Ubuntu Linux</ulink>,
384     <ulink url="&url.freebsd;">FreeBSD (i386)</ulink>,
385     <ulink url="&url.macosx;">MAC OSX</ulink>,
386     <ulink url="&url.solaris;">Solaris</ulink>,
387     Windows 7, Windows XP.
388    </para>
389    <para>
390     Some versions have be known to work on HP/UX,
391     DEC Unix, <ulink url="&url.netbsd;">NetBSD</ulink>,
392     <ulink url="&url.openbsd;">OpenBSD</ulink>,
393     IBM AIX,
394     Data General DG/UX (with some CFLAGS tinkering),
395     SGI/IRIX, DDE Supermax, Apple Macintosh (using the Codewarrior programming
396     environment and the GUSI socket libraries),
397     IBM AS/400 .
398    </para>
399    <para>
400     If you move the software to other platforms, we'd be grateful if you'd
401     let us know about it. If you run into difficulties, we will try to help
402     if we can, and if you solve the problems, we would be happy to include
403     your fixes in the next release. So far, we have mostly avoided
404     <literal>#ifdefs</literal> for individual platforms, and we'd
405     like to keep it that way as far as it makes sense.
406    </para>
407    <para>
408     We maintain a mailing-list for the purpose of announcing new releases and
409     bug-fixes, as well as general discussion. Subscribe by
410     filling-in the form
411     <ulink url="&url.yaz.mailinglist;">here</ulink>.
412     General questions and problems can be directed at
413     <ulink url="&url.yaz.mail;"/>, or the address given at the top of
414      this document.
415    </para>
416   </sect1>
417   <sect1 id="installation.unix"><title>UNIX</title>
418    <para>
419     We provide
420     <ulink url="&url.debian;">Debian GNU/Linux</ulink> (i386 and amd64),
421     <ulink url="&url.ubuntu;">Ubuntu</ulink> (i386 and amd64)
422     and
423     <ulink url="&url.centos;">CentOS</ulink> (amd64 only) packages for &yaz;.
424     You should be able to create packages for other CPUs by building
425     them from the source package.
426    </para>
427    <para>
428     YAZ is also part of several packages repositories. Some of them are
429    </para>
430    <itemizedlist>
431     <listitem>
432      <para>
433       Solaris CSW: <ulink url="http://www.opencsw.org/packages/yaz/"/>
434      </para>
435     </listitem>
436     <listitem>
437      <para>
438       Solaris: <ulink url="http://unixpackages.com"/>
439      </para>
440     </listitem>
441     <listitem>
442      <para>
443       FreeBSD: <ulink url="http://www.freshports.org/net/yaz"/>
444      </para>
445     </listitem>
446     <listitem>
447      <para>
448       Debian: <ulink url="http://packages.debian.org/search?keywords=yaz"/>
449      </para>
450     </listitem>
451     <listitem>
452      <para>
453       Ubuntu: <ulink url="https://launchpad.net/ubuntu/+source/yaz"/>
454      </para>
455     </listitem>
456     <listitem>
457      <para>
458       NetBSD:
459       <ulink url="http://ftp.netbsd.org/pub/pkgsrc/current/pkgsrc/net/yaz/README.html"/>
460      </para>
461     </listitem>
462    </itemizedlist>
463    <sect2 id="installation.source.unix">
464     <title>Compiling from source on Unix</title>
465     <para>
466      Note that if your system doesn't have a native ANSI C compiler, you may
467      have to acquire one separately. We recommend
468      <ulink url="&url.gcc;">GCC</ulink>.
469     </para>
470     <para>
471      If you wish to use character set conversion facilities in &yaz; or if you
472      are compiling &yaz; for use with Zebra it is a good idea to ensure that
473      the iconv library is installed. Some Unixes today already have it
474      - if not, we suggest
475      <ulink url="&url.libiconv;">GNU libiconv</ulink>.
476     </para>
477     <para>
478      YAZ 3.0.16 and later includes a wrapper for the
479      <ulink url="&url.icu;">ICU</ulink>
480      (International Components for Unicode).
481      In order to use this, the developer version of the ICU library
482      must be available. ICU support is recommended for applications
483      such as Pazpar2 and Zebra.
484     </para>
485     <para>
486      The <ulink url="&url.libxslt;">libxslt</ulink>,
487      <ulink url="&url.libxml2;">libxml2</ulink> librararies are required
488      if &yaz; is to support SRU/Solr.
489      These libraries are very portable and should compile out-of-the
490      box on virtually all Unix platforms. It is available in binary
491      forms for Linux and others.
492     </para>
493     <para>
494      The GNU tools
495      <ulink url="&url.autoconf;">Autoconf</ulink>,
496      <ulink url="&url.automake;">Automake</ulink> and
497      <ulink url="&url.libtool;">Libtool</ulink>
498      are used to generate Makefiles and configure &yaz; for the system.
499      You do <emphasis>not</emphasis> need these tools unless you're using the
500      Git version of &yaz;.
501     </para>
502     <para>
503      The CQL parser for &yaz; is built using
504      GNU <ulink url="&url.bison;">Bison</ulink>.
505      This tool is only needed if you're using the Git version of &yaz;.
506     </para>
507     <para>
508      &yaz; includes a tiny ASN.1 compiler. This compiler is
509      written in <ulink url="&url.tcl;">Tcl</ulink>.
510      But as for Bison you do not need it unless you're using Git
511      version of &yaz; or you're using the compiler to build your own codecs
512      for private ASN.1.
513     </para>
514     <para>
515      Generally it should be sufficient to run configure without options,
516      like this:
517     </para>
518     <screen>
519      ./configure
520     </screen>
521     <para>
522      The configure script attempts to use use the C compiler specified by
523      the <literal>CC</literal> environment variable. If not set, GNU C will be
524      used if it is available. The <literal>CFLAGS</literal> environment
525      variable holds options to be passed to the C compiler. If you're using
526      Bourne-compatible shell you may pass something like this to use a
527      particular C compiler with optimization enabled:
528     </para>
529     <screen>
530      CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
531     </screen>
532     <para>
533      To customize &yaz;, the configure script also accepts a set of options.
534      The most important are:
535      <variablelist>
536       <varlistentry>
537        <term>
538         <literal>--prefix</literal>=<replaceable>prefix</replaceable>
539        </term>
540        <listitem>
541         <para>Specifies installation prefix for &yaz;. This is
542         only needed if you run <literal>make install</literal> later to
543         perform a "system" installation. The prefix is
544         <literal>/usr/local</literal> if not specified.
545         </para>
546        </listitem>
547       </varlistentry>
548       <varlistentry>
549        <term>
550         <literal>--enable-tcpd</literal>
551        </term>
552        <listitem>
553         <para>The front end server will be built using Wietse's
554         <ulink url="&url.tcpwrapper;">TCP wrapper library</ulink>.
555         It allows you to allow/deny clients depending on IP number.
556         The TCP wrapper library is often used in GNU/Linux and
557         BSD distributions.
558         See
559         <citerefentry>
560          <refentrytitle>hosts_access</refentrytitle>
561          <manvolnum>5</manvolnum>
562         </citerefentry>
563         and
564         <citerefentry>
565          <refentrytitle>tcpd</refentrytitle>
566          <manvolnum>8</manvolnum>
567          </citerefentry>.
568         </para>
569        </listitem>
570       </varlistentry>
571       <varlistentry>
572        <term>
573         <literal>--enable-threads</literal>
574        </term>
575        <listitem>
576         <para>&yaz; will be built using POSIX threads.
577         Specifically, <constant>_REENTRANT</constant> will be defined during
578         compilation.
579         </para>
580        </listitem>
581       </varlistentry>
582       <varlistentry>
583        <term>
584         <literal>--disable-shared</literal>
585        </term>
586        <listitem>
587         <para>The make process will not create shared
588         libraries (also known as shared objects <filename>.so</filename>).
589         By default, shared libraries are created -
590         equivalent to <literal>--enable-shared</literal>.
591        </para>
592        </listitem>
593       </varlistentry>
594       <varlistentry>
595        <term>
596         <literal>--disable-shared</literal>
597        </term>
598        <listitem>
599         <para>The make process will not create
600         static libraries (<filename>.a</filename>).
601         By default, static libraries are created -
602         equivalent to <literal>--enable-static</literal>.
603         </para>
604        </listitem>
605       </varlistentry>
606       <varlistentry>
607        <term>
608         <literal>--with-iconv</literal>[=<replaceable>prefix</replaceable>]
609        </term>
610        <listitem>
611         <para>Compile &yaz; with iconv library in directory
612         <replaceable>prefix</replaceable>. By default configure will
613         search for iconv on the system. Use this option if it
614         doesn't find iconv. Alternatively,
615         <literal>--without-iconv</literal>, can be used to force &yaz;
616         not to use iconv.
617         </para>
618        </listitem>
619       </varlistentry>
620       <varlistentry>
621        <term>
622         <literal>--with-xslt</literal>[=<replaceable>prefix</replaceable>]
623        </term>
624        <listitem>
625         <para>Compile &yaz; with
626         <ulink url="&url.libxslt;">libxslt</ulink> in directory
627         <replaceable>prefix</replaceable>.
628         Use this option if you want XSLT and XML support.
629         By default, configure will
630         search for libxslt on the system. Use this option if
631         libxslt is not found automatically. Alternatively,
632         <literal>--without-xslt</literal>, can be used to force &yaz;
633         not to use libxslt.
634         </para>
635        </listitem>
636       </varlistentry>
637       <varlistentry>
638        <term>
639         <literal>--with-xml2</literal>[=<replaceable>prefix</replaceable>]
640        </term>
641        <listitem>
642         <para>Compile &yaz; with
643         <ulink url="&url.libxml2;">libxml2</ulink> in directory
644         <replaceable>prefix</replaceable>.
645         Use this option if you want &yaz; to use XML and support SRU/Solr.
646         By default, configure will
647         search for libxml2 on the system. Use this option if
648         libxml2 is not found automatically. Alternatively,
649         <literal>--without-xml2</literal>, can be used to force &yaz;
650         not to use libxml2.
651         </para>
652         <para>
653          Note that option <literal>--with-xslt</literal>
654          also enables libxml2.
655         </para>
656        </listitem>
657       </varlistentry>
658       <varlistentry>
659        <term>
660         <literal>--with-gnutls</literal>[=<replaceable>prefix</replaceable>]
661        </term>
662        <listitem>
663         <para>&yaz; will be linked with the GNU TLS libraries and
664         an SSL COMSTACK will be provided. By default configure enables
665         SSL support for YAZ if the GNU TLS development libraries are found
666         on the system.
667         </para>
668        </listitem>
669       </varlistentry>
670       <varlistentry>
671        <term>
672         <literal>--with-icu</literal>[=<replaceable>prefix</replaceable>]
673        </term>
674        <listitem>
675         <para>&yaz; will be linked the
676         <ulink url="&url.icu;">ICU</ulink> library in the prefix if given.
677         If prefix is not given, the libraries exposed by the script
678         <application>icu-config</application> will be used if found.
679         </para>
680        </listitem>
681       </varlistentry>
682
683       <varlistentry>
684        <term>
685         <literal>--with-libgcrypt</literal>[=<replaceable>prefix</replaceable>]
686        </term>
687        <listitem>
688         <para>&yaz; will be linked with
689         <ulink url="&url.libgcrypt;">Libgcrypt</ulink> in the prefix if given.
690         If prefix is not given, the libraries exposed by the script
691         <application>libgcrypt-config</application> will be used if found.
692         </para>
693        </listitem>
694       </varlistentry>
695       <varlistentry>
696        <term>
697         <literal>--with-memcached</literal>
698        </term>
699        <listitem>
700         <para>&yaz; will be linked with
701         <ulink url="&url.libmemcached;">libMemcached</ulink> to allow
702         for result-set caching for ZOOM.
703         The prefix can not be given. Note that YAZ will only search
704         for libMemcached if Libgcrypt is also enabled.
705         Note that 0.40 of libmemcached is required.
706        </para>
707        </listitem>
708       </varlistentry>
709       <varlistentry>
710        <term>
711         <literal>--with-redis</literal>
712        </term>
713        <listitem>
714         <para>&yaz; will be linked with the hiredis C library
715         to allow for result-set caching for ZOOM on a
716         <ulink url="&url.redis;">redis</ulink> server.
717         The prefix can not be given. Note that YAZ will only search
718         for hiredis if Libgcrypt is also enabled.
719        </para>
720        </listitem>
721       </varlistentry>
722
723      </variablelist>
724     </para>
725     <para>
726      When configured, build the software by typing:
727      <screen>
728       make
729      </screen>
730     </para>
731     <para>
732      The following files are generated by the make process:
733      <variablelist>
734       <varlistentry>
735        <term><filename>src/libyaz.la</filename></term>
736        <listitem><para>
737         Main &yaz; library. This is no ordinary library. It's
738         a Libtool archive.
739         By default, &yaz; creates a static library in
740         <filename>lib/.libs/libyaz.a</filename>.
741        </para></listitem>
742       </varlistentry>
743       <varlistentry>
744        <term><filename>src/libyaz_server.la</filename></term>
745        <listitem><para>
746          Generic Frontend server. This is an add-on for libyaz.la.
747          Code in this library uses POSIX threads functions - if POSIX
748          threads are available on the platform.
749         </para></listitem>
750       </varlistentry>
751       <varlistentry>
752        <term><filename>src/libyaz_icu.la</filename></term>
753        <listitem><para>
754         Functions that wrap the ICU library.
755         </para></listitem>
756       </varlistentry>
757       <varlistentry>
758        <term><filename>ztest/yaz-ztest</filename></term>
759        <listitem><para>Test Z39.50 server.
760        </para></listitem>
761       </varlistentry>
762       <varlistentry>
763        <term><filename>client/yaz-client</filename></term>
764        <listitem><para>Z39.50 client for testing the protocol.
765        See chapter <link linkend="yaz-client">
766        YAZ client</link> for more information.
767        </para></listitem>
768       </varlistentry>
769       <varlistentry>
770        <term><filename>util/yaz-config</filename></term>
771        <listitem><para>A Bourne-shell script, generated by configure, that
772        specifies how external applications should compile - and link with
773        &yaz;.
774        </para></listitem>
775       </varlistentry>
776       <varlistentry>
777        <term><filename>util/yaz-asncomp</filename></term>
778        <listitem><para>The ASN.1 compiler for &yaz;. Requires the
779        Tcl Shell, <application>tclsh</application>, in
780        <literal>PATH</literal> to operate.
781        </para></listitem>
782       </varlistentry>
783       <varlistentry>
784        <term><filename>util/yaz-iconv</filename></term>
785        <listitem><para>This program converts data in one character set to
786        another. This command exercises the YAZ character set
787        conversion API.
788        </para></listitem>
789       </varlistentry>
790       <varlistentry>
791        <term><filename>util/yaz-marcdump</filename></term>
792        <listitem><para>This program parses ISO2709 encoded MARC records
793        and prints them in line-format or XML.
794        </para></listitem>
795       </varlistentry>
796       <varlistentry>
797        <term><filename>util/yaz-icu</filename></term>
798        <listitem><para>This program exposes the ICU wrapper library if that
799        is enabled for YAZ. Only if ICU is available this program is
800        useful.
801        </para></listitem>
802       </varlistentry>
803       <varlistentry>
804        <term><filename>util/yaz-url</filename></term>
805        <listitem><para>This program is a simple HTTP page fetcher ala
806        wget or curl.
807        </para></listitem>
808       </varlistentry>
809       <varlistentry>
810        <term><filename>zoom/zoomsh</filename></term>
811        <listitem><para>
812         A simple shell implemented on top of the
813         <link linkend="zoom">ZOOM</link> functions.
814         The shell is a command line application that allows you to enter
815         simple commands to perform ZOOM operations.
816        </para></listitem>
817       </varlistentry>
818       <varlistentry>
819        <term><filename>zoom/zoomtst1</filename>,
820        <filename>zoom/zoomtst2</filename>, ..</term>
821        <listitem><para>
822         Several small applications that demonstrates the ZOOM API.
823        </para></listitem>
824       </varlistentry>
825      </variablelist>
826     </para>
827     <para>
828      If you wish to install &yaz; in system directories
829      <filename>/usr/local/bin</filename>,
830      <filename>/usr/local/lib</filename> .. etc, you can type:
831     </para>
832     <screen>
833      make install
834     </screen>
835     <para>
836      You probably need to have root access in order to perform this.
837      You must specify the <literal>--prefix</literal> option for configure if
838      you wish to install &yaz; in other directories than the default
839      <filename>/usr/local/</filename>.
840     </para>
841     <para>
842      If you wish to perform an un-installation of &yaz;, use:
843     </para>
844     <screen>
845      make uninstall
846     </screen>
847     <para>
848      This will only work if you haven't reconfigured &yaz; (and therefore
849      changed installation prefix). Note that uninstall will not
850      remove directories created by make install, e.g.
851      <filename>/usr/local/include/yaz</filename>.
852     </para>
853    </sect2>
854    <sect2 id="installation-linking-yaz-unix">
855     <title>How to make apps using YAZ on UNIX</title>
856     <para>
857      This section describes how to compile - and link your own
858      applications using the &yaz; toolkit.
859      If you're used to Makefiles this shouldn't be hard. As for
860      other libraries you have used before, you need to set a proper include
861      path for your C/C++ compiler and specify the location of
862      &yaz; libraries. You can do it by hand, but generally we suggest
863      you use the <filename>yaz-config</filename> that is generated
864      by <filename>configure</filename>. This is especially
865      important if you're using the threaded version of &yaz; which
866      require you to pass more options to your linker/compiler.
867     </para>
868     <para>
869      The <filename>yaz-config</filename> script accepts command line
870      options that makes the <filename>yaz-config</filename> script print
871      options that you should use in your make process.
872      The most important ones are:
873      <literal>--cflags</literal>, <literal>--libs</literal>
874      which prints C compiler flags, and linker flags respectively.
875     </para>
876     <para>
877      A small and complete <literal>Makefile</literal> for a C
878      application consisting of one source file,
879      <filename>myprog.c</filename>, may look like this:
880      <screen>
881       YAZCONFIG=/usr/local/bin/yaz-config
882       CFLAGS=`$(YAZCONFIG) --cflags`
883       LIBS=`$(YAZCONFIG) --libs`
884       myprog: myprog.o
885          $(CC) $(CFLAGS) -o myprog myprog.o $(LIBS)
886       </screen>
887     </para>
888     <para>
889      The CFLAGS variable consists of a C compiler directive that will set
890      the include path to the <emphasis>parent</emphasis> directory
891      of <filename>yaz</filename>. That is, if &yaz; header files were
892      installed in <filename>/usr/local/include/yaz</filename>,
893      then include path is set to <filename>/usr/local/include</filename>.
894      Therefore, in your applications you should use
895      <screen>
896       #include &lt;yaz/proto.h>
897      </screen>
898      and <emphasis>not</emphasis>
899      <screen>
900       #include &lt;proto.h>
901      </screen>
902     </para>
903     <para>
904      For Libtool users, the <filename>yaz-config</filename> script provides
905      a different variant of option <literal>--libs</literal>, called
906      <literal>--lalibs</literal> that returns the name of the
907      Libtool archive(s) for &yaz; rather than the ordinary ones.
908     </para>
909     <para>
910      For applications using the threaded version of &yaz;,
911      specify <literal>threads</literal> after the
912      other options. When <literal>threads</literal> is given,
913      more flags and linker flags will be printed by
914      <filename>yaz-config</filename>. If our previous example was
915       using threads, you'd have to modify the lines that set
916      <literal>CFLAGS</literal> and <literal>LIBS</literal> as
917      follows:
918      <screen>
919       CFLAGS=`$(YAZCONFIG) --cflags threads`
920       LIBS=`$(YAZCONFIG) --libs threads`
921      </screen>
922      There is no need specify POSIX thread libraries in your Makefile.
923      The <literal>LIBS</literal> variable includes that as well.
924     </para>
925    </sect2>
926   </sect1>
927   <sect1 id="installation.win32">
928    <title>Windows</title>
929    <para>The easiest way to install YAZ on Windows is by downloading
930    an installer from
931    <ulink url="&url.yaz.download.win32;">here</ulink>.
932    The installer comes with source too - in case you wish to
933    compile YAZ with different compiler options, etc.
934    </para>
935
936    <sect2 id="installation.win32.source">
937     <title>Compiling from Source on Windows</title>
938     <para>
939      &yaz; is shipped with "makefiles" for the NMAKE tool that comes
940      with <ulink url="&url.vstudio;">
941      Microsoft Visual Studio</ulink>. It has been tested with
942      Microsoft Visual Studio 2013.
943     </para>
944     <para>
945      Start a command prompt and switch the sub directory
946      <filename>WIN</filename> where the file <filename>makefile</filename>
947      is located. Customize the installation by editing the
948      <filename>makefile</filename> file (for example by using notepad).
949      The following summarizes the most important settings in that file:
950      <variablelist>
951       <varlistentry>
952        <term><literal>DEBUG</literal></term>
953        <listitem><para>
954         If set to 1, the software is
955         compiled with debugging libraries (code generation is
956         multi-threaded debug DLL).
957         If set to 0, the software is compiled with release libraries
958         (code generation is multi-threaded DLL).
959        </para></listitem>
960       </varlistentry>
961       <varlistentry>
962        <term><literal>HAVE_TCL</literal>, <literal>TCL</literal></term>
963        <listitem><para>
964         If <literal>HAVE_TCL</literal> is set to 1, nmake will
965         use the ASN.1 compiler (<ulink url="&url.tcl;">Tcl</ulink> based).
966         You must set <literal>TCL</literal> to the full path of the Tcl
967         interpreter. A Windows version of Tcl is part of
968         <ulink url="&url.gitwindows;">Git for Windows</ulink>.
969        </para>
970        <para>
971         If you do not have Tcl installed, set
972         <literal>HAVE_TCL</literal> to 0.
973        </para></listitem>
974       </varlistentry>
975       <varlistentry>
976        <term><literal>HAVE_BISON</literal>,
977        <literal>BISON</literal></term>
978        <listitem><para>
979         If GNU Bison is present, you might set <literal>HAVE_BISON</literal>
980         to 1 and specify the Bison executable in <literal>BISON</literal>.
981         Bison is only required if you use the Git version of
982         YAZ or if you modify the grammar for CQL
983         (<filename>cql.y</filename>).
984        </para>
985        <para>
986         A Windows version of GNU Bison is part of
987         <ulink url="&url.gitwindows;">Git for Windows</ulink>.
988        </para></listitem>
989       </varlistentry>
990       <varlistentry>
991        <term><literal>HAVE_ICONV</literal>,
992        <literal>ICONV_DIR</literal></term>
993        <listitem><para>
994         If <literal>HAVE_ICONV</literal> is set to 1, YAZ is compiled
995         with iconv support. In this configuration, set
996         <literal>ICONV_DIR</literal> to the iconv source directory.
997        </para></listitem>
998       </varlistentry>
999       <varlistentry>
1000        <term><literal>HAVE_LIBXML2</literal>,
1001        <literal>LIBXML2_DIR</literal></term>
1002        <listitem>
1003         <para>
1004          If <literal>HAVE_LIBXML2</literal> is set to 1, YAZ is compiled
1005          with SRU support. In this configuration, set
1006          <literal>LIBXML2_DIR</literal> to the
1007          <ulink url="&url.libxml2;">libxml2</ulink> source directory.
1008         </para>
1009         <para>
1010          You can get pre-compiled Libxml2+Libxslt DLLs and headers from
1011          <ulink url="&url.libxml2.download.windows;">here</ulink>.
1012          Should you with to compile those libraries yourself, refer to
1013          to <xref linkend="installation.windows.libxml2"/>
1014         </para>
1015        </listitem>
1016       </varlistentry>
1017       <varlistentry>
1018        <term><literal>HAVE_LIBXSLT</literal>,
1019        <literal>LIBXSLT_DIR</literal></term>
1020        <listitem>
1021         <para>
1022          If <literal>HAVE_LIBXSLT</literal> is set to 1, YAZ is compiled
1023          with XSLT support. In this configuration, set
1024          <literal>LIBXSLT_DIR</literal> to the
1025          <ulink url="&url.libxslt;">libxslt</ulink> source directory.
1026         </para>
1027         <note>
1028          <para>
1029           libxslt depends on libxml2.
1030          </para>
1031         </note>
1032        </listitem>
1033       </varlistentry>
1034       <varlistentry>
1035        <term><literal>HAVE_ICU</literal>,
1036        <literal>ICU_DIR</literal></term>
1037        <listitem>
1038         <para>
1039          If <literal>HAVE_ICU</literal> is set to 1, YAZ is compiled
1040          with <ulink url="&url.icu;">ICU</ulink> support.
1041          In this configuration, set
1042          <literal>ICU_DIR</literal> to the
1043          <ulink url="&url.icu;">ICU</ulink> source directory.
1044         </para>
1045        </listitem>
1046       </varlistentry>
1047      </variablelist>
1048     </para>
1049     <para>
1050      When satisfied with the settings in the makefile, type
1051      <screen>
1052       nmake
1053      </screen>
1054     </para>
1055     <note>
1056      <para>
1057       If the <filename>nmake</filename> command is not found on your system
1058       you probably haven't defined the environment variables required to
1059       use that tool. To fix that, find and run the batch file
1060       <filename>vcvars32.bat</filename>. You need to run it from within
1061       the command prompt or set the environment variables "globally";
1062       otherwise it doesn't work.
1063      </para>
1064     </note>
1065     <para>
1066      If you wish to recompile &yaz; - for example if you modify
1067      settings in the <filename>makefile</filename> you can delete
1068      object files, etc by running.
1069      <screen>
1070       nmake clean
1071      </screen>
1072     </para>
1073     <para>
1074      The following files are generated upon successful compilation:
1075      <variablelist>
1076       <varlistentry>
1077        <term><filename>bin/yaz&soversion;.dll</filename> /
1078        <filename>bin/yaz&soversion;d.dll</filename></term>
1079        <listitem><para>
1080         &yaz; Release/Debug DLL.
1081        </para></listitem>
1082       </varlistentry>
1083       <varlistentry>
1084        <term><filename>lib/yaz&soversion;.lib</filename> /
1085        <filename>lib/yaz&soversion;d.lib</filename></term>
1086        <listitem><para>
1087         Import library for <filename>yaz&soversion;.dll</filename> /
1088         <filename>yaz&soversion;d.dll</filename>.
1089       </para></listitem>
1090       </varlistentry>
1091       <varlistentry>
1092        <term><filename>bin/yaz_cond&soversion;.dll</filename> /
1093        <filename>bin/yaz_cond&soversion;d.dll</filename></term>
1094        <listitem><para>
1095         Release/Debug DLL for condition variable utilities (condvar.c).
1096        </para></listitem>
1097       </varlistentry>
1098       <varlistentry>
1099        <term><filename>lib/yaz_cond&soversion;.lib</filename> /
1100        <filename>lib/yaz_cond&soversion;d.lib</filename></term>
1101        <listitem><para>
1102         Import library for <filename>yaz_cond&soversion;.dll</filename> /
1103         <filename>yaz_cond&soversion;d.dll</filename>.
1104        </para></listitem>
1105       </varlistentry>
1106       <varlistentry>
1107        <term><filename>bin/yaz_icu&soversion;.dll</filename> /
1108        <filename>bin/yaz_icu&soversion;d.dll</filename></term>
1109        <listitem><para>
1110         Release/Debug DLL for the ICU wrapper utility.
1111         Only build if HAVE_ICU is 1.
1112        </para></listitem>
1113       </varlistentry>
1114       <varlistentry>
1115        <term><filename>lib/yaz_icu&soversion;.lib</filename> /
1116        <filename>lib/yaz_icu&soversion;d.lib</filename></term>
1117        <listitem><para>
1118         Import library for <filename>yaz_icu&soversion;.dll</filename> /
1119         <filename>yaz_icu&soversion;d.dll</filename>.
1120        </para></listitem>
1121       </varlistentry>
1122       <varlistentry>
1123        <term><filename>bin/yaz-ztest.exe</filename></term>
1124        <listitem><para>
1125         Z39.50 multi-threaded test/example server. It's a WIN32
1126         console application.
1127       </para></listitem>
1128       </varlistentry>
1129       <varlistentry>
1130        <term><filename>bin/yaz-client.exe</filename></term>
1131        <listitem><para>
1132         &yaz; Z39.50 client application. It's a WIN32 console application.
1133         See chapter <link linkend="yaz-client">YAZ client</link> for more
1134         information.
1135       </para></listitem>
1136       </varlistentry>
1137       <varlistentry>
1138        <term><filename>bin/yaz-icu.exe</filename></term>
1139        <listitem><para>This program exposes the ICU wrapper library if that
1140        is enabled for YAZ. Only if ICU is available this program is
1141        built.
1142       </para></listitem>
1143       </varlistentry>
1144       <varlistentry>
1145        <term><filename>bin/zoomsh.exe</filename></term>
1146        <listitem><para>
1147         Simple console application implemented on top of the
1148         <link linkend="zoom">ZOOM</link> functions.
1149         The application is a command line shell that allows you to enter
1150         simple commands to perform ZOOM operations.
1151       </para></listitem>
1152       </varlistentry>
1153       <varlistentry>
1154        <term><filename>bin/zoomtst1.exe</filename>,
1155        <filename>bin/zoomtst2.exe</filename>, ..</term>
1156        <listitem><para>
1157         Several small applications that demonstrate the ZOOM API.
1158       </para></listitem>
1159       </varlistentry>
1160      </variablelist>
1161     </para>
1162    </sect2>
1163
1164    <sect2 id="installation-linking-yaz-win32">
1165     <title>How to make apps using YAZ on Windows</title>
1166     <para>
1167      This section will go though the process of linking your Windows
1168      applications with &yaz;.
1169     </para>
1170     <para>
1171      Some people are confused by the fact that we use the nmake
1172      tool to build &yaz;. They think they have to do that too - in order
1173      to make their Windows applications work with &yaz;. The good news is that
1174      you don't have to. You can use the integrated environment of
1175      Visual Studio if desired for your own application.
1176     </para>
1177     <para>
1178      When setting up a project or Makefile you have to set the following:
1179      <variablelist>
1180       <varlistentry>
1181        <term>include path</term>
1182        <listitem><para>
1183         Set it to the <filename>include</filename> directory of &yaz;.
1184         </para></listitem>
1185       </varlistentry>
1186       <varlistentry>
1187        <term>import library <filename>yaz&soversion;.lib</filename></term>
1188        <listitem><para>
1189         You must link with this library. It's located in the
1190         sub directory <filename>lib</filename> of &yaz;.
1191         If you want to link with the debug version of &yaz;, you must
1192         link against <filename>yaz&soversion;d.lib</filename> instead.
1193        </para></listitem>
1194       </varlistentry>
1195       <varlistentry>
1196        <term>dynamic link library
1197        <filename>yaz&soversion;.dll</filename>
1198        </term>
1199        <listitem><para>
1200         This DLL must be in your execution path when you invoke
1201         your application. Specifically, you should distribute this
1202         DLL with your application.
1203        </para></listitem>
1204       </varlistentry>
1205      </variablelist>
1206     </para>
1207    </sect2>
1208
1209    <sect2 id="installation.windows.libxml2">
1210     <title>Compiling Libxml2 and Libxslt on windows</title>
1211     <para>
1212      Download libxml2 and Libxslt source and unpack it.
1213      In the example below we install  Libxml2 2.9.2 and Libxslt 1.1.28
1214      for 32-bit, so we  use the destination directories
1215      libxml2.2.9.2.win32 and libxslt-1.1.28.win32 to reflect both
1216      version and architecture.
1217      <screen>
1218       cd win32
1219       cscript configure.js prefix=c:\libxml2-2.9.2.win32 iconv=no
1220       nmake
1221       nmake install
1222      </screen>
1223     </para>
1224     <note>
1225      <para>
1226       There's an error in <filename>configure.js</filename> for Libxml2 2.9.2.
1227       Line 17 should be assigned to <filename>configure.ac</filename>
1228       rather than <filename>configure.in</filename>.
1229      </para>
1230     </note>
1231     <para>
1232      For Libxslt it is similar. We must ensure that compilation of
1233      Libxslt links against the already installed libxml2.
1234      <screen>
1235       cd win32
1236       cscript configure.js prefix=c:\libxslt-1.1.28.win32 iconv=no \
1237           lib=c:\libxml2-2.9.2.win32\lib \
1238           include=c:\libxml2-2.9.2.win32\include\libxml2
1239       nmake
1240       nmake install
1241      </screen>
1242     </para>
1243    </sect2>
1244
1245   </sect1>
1246  </chapter>
1247  <!--
1248      ### Still to document:
1249      ZOOM_connection_errcode(c)
1250      ZOOM_connection_errmsg(c)
1251      ZOOM_connection_addinfo(c)
1252      ZOOM_connection_addinfo(c)
1253      ZOOM_connection_diagset(c);
1254      ZOOM_connection_save_apdu_wrbuf
1255      ZOOM_diag_str(error)
1256      ZOOM_resultset_record_immediate(s, pos)
1257      ZOOM_resultset_cache_reset(r)
1258      ZOOM_options_set_callback(opt, function, handle)
1259      ZOOM_options_create_with_parent2(parent1, parent2)
1260      ZOOM_options_getl(opt, name, len)
1261      ZOOM_options_setl(opt, name, value, len)
1262      ZOOM_options_get_bool(opt, name, defa)
1263      ZOOM_options_get_int(opt, name, defa)
1264      ZOOM_options_set_int(opt, name, value)
1265  -->
1266  <chapter id="zoom">
1267   <title>ZOOM</title>
1268   <para>
1269    &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is
1270    an initiative started by Mike Taylor (Mike is from the UK, which
1271    explains the peculiar name of the model). The goal of &zoom; is to
1272    provide a common Z39.50 client API not bound to a particular
1273    programming language or toolkit.
1274   </para>
1275   <para>
1276    From YAZ version 2.1.12, <ulink url="&url.sru;">SRU</ulink> is supported.
1277    You can make SRU ZOOM connections by specifying scheme
1278    <literal>http://</literal> for the hostname for a connection.
1279    The dialect of SRU used is specified by the value of the
1280    connection's <literal>sru</literal> option, which may be SRU over
1281    HTTP GET (<literal>get</literal>),
1282    SRU over HTTP POST (<literal>post</literal>), (SRU over
1283    SOAP) (<literal>soap</literal>) or <literal>solr</literal>
1284    (<ulink url="&url.solr;">Solr</ulink> Web Service).
1285    Using the facility for embedding options in target strings, a
1286    connection can be forced to use SRU rather the SRW (the default) by
1287    prefixing the target string with <literal>sru=get,</literal>, like this:
1288    <literal>sru=get,http://sru.miketaylor.org.uk:80/sru.pl</literal>
1289   </para>
1290   <para>
1291    <ulink url="&url.solr;">Solr</ulink>  protocol support was added to
1292    YAZ in version 4.1.0, as a dialect of a SRU protocol, since both are
1293    HTTP based protocols.
1294   </para>
1295   <para>
1296    The lack of a simple Z39.50 client API for &yaz; has become more
1297    and more apparent over time. So when the first &zoom; specification
1298    became available,
1299    an implementation for &yaz; was quickly developed. For the first time, it is
1300    now as easy (or easier!) to develop clients 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.type">
2579     <title>Extended Service Type</title>
2580     <tgroup cols="2">
2581      <colspec colwidth="3*" colname="value"></colspec>
2582      <colspec colwidth="7*" colname="description"></colspec>
2583      <thead>
2584       <row>
2585        <entry>Type</entry>
2586        <entry>Description</entry>
2587       </row>
2588      </thead>
2589      <tbody>
2590       <row>
2591        <entry>itemorder</entry><entry>Item Order</entry>
2592       </row>
2593       <row>
2594        <entry>update</entry><entry>Record Update</entry>
2595       </row>
2596       <row>
2597        <entry>create</entry><entry>Database Create</entry>
2598       </row>
2599       <row>
2600        <entry>drop</entry><entry>Database Drop</entry>
2601       </row>
2602       <row>
2603        <entry>commit</entry><entry>Commit Operation</entry>
2604       </row>
2605      </tbody>
2606     </tgroup>
2607    </table>
2608
2609    <table frame="top" id="zoom.extendedservices.options">
2610     <title>Extended Service Common Options</title>
2611     <tgroup cols="3">
2612      <colspec colwidth="4*" colname="name"></colspec>
2613      <colspec colwidth="7*" colname="description"></colspec>
2614      <colspec colwidth="3*" colname="default"></colspec>
2615      <thead>
2616       <row>
2617        <entry>Option</entry>
2618        <entry>Description</entry>
2619        <entry>Default</entry>
2620       </row>
2621      </thead>
2622      <tbody>
2623       <row>
2624        <entry>package-name</entry>
2625        <entry>Extended Service Request package name. Must be specified
2626        as part of a request</entry>
2627        <entry>none</entry>
2628       </row>
2629       <row>
2630        <entry>user-id</entry>
2631        <entry>User ID of Extended Service Package. Is a request option</entry>
2632        <entry>none</entry>
2633       </row>
2634       <row>
2635        <entry>function</entry>
2636        <entry>
2637         Function of package - one of <literal>create</literal>,
2638         <literal>delete</literal>, <literal>modify</literal>. Is
2639         a request option.
2640        </entry>
2641        <entry><literal>create</literal></entry>
2642       </row>
2643       <row>
2644        <entry>waitAction</entry>
2645        <entry>
2646         Wait action for package. Possible values:
2647         <literal>wait</literal>, <literal>waitIfPossible</literal>,
2648         <literal>dontWait</literal> or <literal>dontReturnPackage</literal>.
2649        </entry>
2650        <entry><literal>waitIfPossible</literal></entry>
2651       </row>
2652       <row>
2653        <entry>targetReference</entry>
2654        <entry>
2655         Target Reference. This is part of the response as returned
2656         by the server. Read it after a successful operation.
2657        </entry>
2658        <entry><literal>none</literal></entry>
2659       </row>
2660      </tbody>
2661     </tgroup>
2662    </table>
2663    <sect2 id="zoom.item.order">
2664     <title>Item Order</title>
2665     <para>
2666      For Item Order, <literal>type</literal> must be set to
2667      <literal>itemorder</literal> in
2668      <function>ZOOM_package_send</function>.
2669     </para>
2670
2671     <table frame="top" id="zoom.item.order.options">
2672      <title>Item Order Options</title>
2673      <tgroup cols="3">
2674       <colspec colwidth="4*" colname="name"></colspec>
2675       <colspec colwidth="7*" colname="description"></colspec>
2676       <colspec colwidth="3*" colname="default"></colspec>
2677       <thead>
2678        <row>
2679         <entry>Option</entry>
2680         <entry>Description</entry>
2681         <entry>Default</entry>
2682        </row>
2683       </thead>
2684       <tbody>
2685        <row>
2686         <entry>contact-name</entry>
2687         <entry>ILL contact name</entry>
2688         <entry>none</entry>
2689        </row>
2690        <row>
2691         <entry>contact-phone</entry>
2692         <entry>ILL contact phone</entry>
2693         <entry>none</entry>
2694        </row>
2695        <row>
2696         <entry>contact-email</entry>
2697         <entry>ILL contact email</entry>
2698         <entry>none</entry>
2699        </row>
2700        <row>
2701         <entry>itemorder-setname</entry>
2702         <entry>Name of result set for record</entry>
2703         <entry>default</entry>
2704        </row>
2705        <row>
2706         <entry>itemorder-item</entry>
2707         <entry>Position for item (record) requested. An integer</entry>
2708         <entry>1</entry>
2709        </row>
2710       </tbody>
2711      </tgroup>
2712     </table>
2713     <para>
2714      There are two variants of item order: ILL-variant and
2715      XML document variant. In order to use the XML variant the setting
2716      <literal>doc</literal> must hold the XML item order document. If that
2717      setting is unset, the ILL-variant is used.
2718     </para>
2719
2720     <table frame="top" id="zoom.illrequest.options">
2721      <title>ILL Request Options</title>
2722      <tgroup cols="1">
2723       <colspec colwidth="4*" colname="name"></colspec>
2724       <thead>
2725        <row>
2726         <entry>Option</entry>
2727        </row>
2728       </thead>
2729       <tbody>
2730        <row><entry>protocol-version-num</entry></row>
2731        <row><entry>transaction-id,initial-requester-id,person-or-institution-symbol,person</entry></row>
2732        <row><entry>transaction-id,initial-requester-id,person-or-institution-symbol,institution</entry></row>
2733        <row><entry>transaction-id,initial-requester-id,name-of-person-or-institution,name-of-person</entry></row>
2734        <row><entry>transaction-id,initial-requester-id,name-of-person-or-institution,name-of-institution</entry></row>
2735        <row><entry>transaction-id,transaction-group-qualifier</entry></row>
2736        <row><entry>transaction-id,transaction-qualifier</entry></row>
2737        <row><entry>transaction-id,sub-transaction-qualifier</entry></row>
2738        <row><entry>service-date-time,this,date</entry></row>
2739        <row><entry>service-date-time,this,time</entry></row>
2740        <row><entry>service-date-time,original,date</entry></row>
2741        <row><entry>service-date-time,original,time</entry></row>
2742        <row><entry>requester-id,person-or-institution-symbol,person</entry></row>
2743        <row><entry>requester-id,person-or-institution-symbol,institution</entry></row>
2744        <row><entry>requester-id,name-of-person-or-institution,name-of-person</entry></row>
2745        <row><entry>requester-id,name-of-person-or-institution,name-of-institution</entry></row>
2746        <row><entry>responder-id,person-or-institution-symbol,person</entry></row>
2747        <row><entry>responder-id,person-or-institution-symbol,institution</entry></row>
2748        <row><entry>responder-id,name-of-person-or-institution,name-of-person</entry></row>
2749        <row><entry>responder-id,name-of-person-or-institution,name-of-institution</entry></row>
2750        <row><entry>transaction-type</entry></row>
2751        <row><entry>delivery-address,postal-address,name-of-person-or-institution,name-of-person</entry></row>
2752        <row><entry>delivery-address,postal-address,name-of-person-or-institution,name-of-institution</entry></row>
2753        <row><entry>delivery-address,postal-address,extended-postal-delivery-address</entry></row>
2754        <row><entry>delivery-address,postal-address,street-and-number</entry></row>
2755        <row><entry>delivery-address,postal-address,post-office-box</entry></row>
2756        <row><entry>delivery-address,postal-address,city</entry></row>
2757        <row><entry>delivery-address,postal-address,region</entry></row>
2758        <row><entry>delivery-address,postal-address,country</entry></row>
2759        <row><entry>delivery-address,postal-address,postal-code</entry></row>
2760        <row><entry>delivery-address,electronic-address,telecom-service-identifier</entry></row>
2761        <row><entry>delivery-address,electronic-address,telecom-service-addreess</entry></row>
2762        <row><entry>billing-address,postal-address,name-of-person-or-institution,name-of-person</entry></row>
2763        <row><entry>billing-address,postal-address,name-of-person-or-institution,name-of-institution</entry></row>
2764        <row><entry>billing-address,postal-address,extended-postal-delivery-address</entry></row>
2765        <row><entry>billing-address,postal-address,street-and-number</entry></row>
2766        <row><entry>billing-address,postal-address,post-office-box</entry></row>
2767        <row><entry>billing-address,postal-address,city</entry></row>
2768        <row><entry>billing-address,postal-address,region</entry></row>
2769        <row><entry>billing-address,postal-address,country</entry></row>
2770        <row><entry>billing-address,postal-address,postal-code</entry></row>
2771        <row><entry>billing-address,electronic-address,telecom-service-identifier</entry></row>
2772        <row><entry>billing-address,electronic-address,telecom-service-addreess</entry></row>
2773        <row><entry>ill-service-type</entry></row>
2774        <row><entry>requester-optional-messages,can-send-RECEIVED</entry></row>
2775        <row><entry>requester-optional-messages,can-send-RETURNED</entry></row>
2776        <row><entry>requester-optional-messages,requester-SHIPPED</entry></row>
2777        <row><entry>requester-optional-messages,requester-CHECKED-IN</entry></row>
2778        <row><entry>search-type,level-of-service</entry></row>
2779        <row><entry>search-type,need-before-date</entry></row>
2780        <row><entry>search-type,expiry-date</entry></row>
2781        <row><entry>search-type,expiry-flag</entry></row>
2782        <row><entry>place-on-hold</entry></row>
2783        <row><entry>client-id,client-name</entry></row>
2784        <row><entry>client-id,client-status</entry></row>
2785        <row><entry>client-id,client-identifier</entry></row>
2786        <row><entry>item-id,item-type</entry></row>
2787        <row><entry>item-id,call-number</entry></row>
2788        <row><entry>item-id,author</entry></row>
2789        <row><entry>item-id,title</entry></row>
2790        <row><entry>item-id,sub-title</entry></row>
2791        <row><entry>item-id,sponsoring-body</entry></row>
2792        <row><entry>item-id,place-of-publication</entry></row>
2793        <row><entry>item-id,publisher</entry></row>
2794        <row><entry>item-id,series-title-number</entry></row>
2795        <row><entry>item-id,volume-issue</entry></row>
2796        <row><entry>item-id,edition</entry></row>
2797        <row><entry>item-id,publication-date</entry></row>
2798        <row><entry>item-id,publication-date-of-component</entry></row>
2799        <row><entry>item-id,author-of-article</entry></row>
2800        <row><entry>item-id,title-of-article</entry></row>
2801        <row><entry>item-id,pagination</entry></row>
2802        <row><entry>item-id,ISBN</entry></row>
2803        <row><entry>item-id,ISSN</entry></row>
2804        <row><entry>item-id,additional-no-letters</entry></row>
2805        <row><entry>item-id,verification-reference-source</entry></row>
2806        <row><entry>copyright-complicance</entry></row>
2807        <row><entry>retry-flag</entry></row>
2808        <row><entry>forward-flag</entry></row>
2809        <row><entry>requester-note</entry></row>
2810        <row><entry>forward-note</entry></row>
2811       </tbody>
2812      </tgroup>
2813     </table>
2814    </sect2>
2815    <sect2 id="zoom.record.update">
2816     <title>Record Update</title>
2817     <para>
2818      For Record Update, <literal>type</literal> must be set to
2819      <literal>update</literal> in
2820      <function>ZOOM_package_send</function>.
2821     </para>
2822     <table frame="top" id="zoom.record.update.options">
2823      <title>Record Update Options</title>
2824      <tgroup cols="3">
2825       <colspec colwidth="4*" colname="name"></colspec>
2826       <colspec colwidth="7*" colname="description"></colspec>
2827       <colspec colwidth="3*" colname="default"></colspec>
2828       <thead>
2829        <row>
2830         <entry>Option</entry>
2831         <entry>Description</entry>
2832         <entry>Default</entry>
2833        </row>
2834       </thead>
2835       <tbody>
2836        <row>
2837         <entry>action</entry>
2838         <entry>
2839          The update action. One of
2840          <literal>specialUpdate</literal>,
2841          <literal>recordInsert</literal>,
2842          <literal>recordReplace</literal>,
2843          <literal>recordDelete</literal>,
2844          <literal>elementUpdate</literal>.
2845         </entry>
2846         <entry><literal>specialUpdate (recordInsert for updateVersion=1 which does not support specialUpdate)</literal></entry>
2847        </row>
2848        <row>
2849         <entry>recordIdOpaque</entry>
2850         <entry>Opaque Record ID</entry>
2851         <entry>none</entry>
2852        </row>
2853        <row>
2854         <entry>recordIdNumber</entry>
2855         <entry>Record ID number</entry>
2856         <entry>none</entry>
2857        </row>
2858        <row>
2859         <entry>record</entry>
2860         <entry>The record itself</entry>
2861         <entry>none</entry>
2862        </row>
2863        <row>
2864         <entry>recordOpaque</entry>
2865         <entry>Specifies an opaque record which is
2866           encoded as an ASN.1 ANY type with the OID as tiven by option
2867           <literal>syntax</literal> (see below).
2868           Option <literal>recordOpaque</literal> is an alternative
2869           to record - and <literal>record</literal> option (above) is
2870           ignored if recordOpaque is set. This option is only available in
2871           YAZ 3.0.35 and later and is meant to facilitate Updates with
2872           servers from OCLC.
2873         </entry>
2874         <entry>none</entry>
2875        </row>
2876        <row>
2877         <entry>syntax</entry>
2878         <entry>The record syntax (transfer syntax). Is a string that
2879          is a known record syntax.
2880         </entry>
2881         <entry>no syntax</entry>
2882        </row>
2883        <row>
2884         <entry>databaseName</entry>
2885         <entry>Database from connection object</entry>
2886         <entry>Default</entry>
2887        </row>
2888        <row>
2889         <entry>correlationInfo.note</entry>
2890         <entry>Correlation Info Note (string)</entry>
2891         <entry>none</entry>
2892        </row>
2893        <row>
2894         <entry>correlationInfo.id</entry>
2895         <entry>Correlation Info ID (integer)</entry>
2896         <entry>none</entry>
2897        </row>
2898        <row>
2899         <entry>elementSetName</entry>
2900         <entry>Element Set for Record</entry>
2901         <entry>none</entry>
2902        </row>
2903        <row>
2904         <entry>updateVersion</entry>
2905         <entry>Record Update version which holds one of the values
2906          1, 2 or 3. Each version has a distinct OID:
2907          1.2.840.10003.9.5
2908          (<ulink url="&url.z39.50.extupdate1;">first version</ulink>) ,
2909          1.2.840.10003.9.5.1
2910          (second version) and
2911          1.2.840.10003.9.5.1.1
2912          (<ulink url="&url.z39.50.extupdate3;">third and
2913           newest version</ulink>).
2914         </entry>
2915         <entry>3</entry>
2916        </row>
2917       </tbody>
2918      </tgroup>
2919     </table>
2920
2921    </sect2>
2922
2923    <sect2 id="zoom.database.create"><title>Database Create</title>
2924     <para>
2925      For Database Create, <literal>type</literal> must be set to
2926      <literal>create</literal> in
2927      <function>ZOOM_package_send</function>.
2928     </para>
2929
2930     <table frame="top" id="zoom.database.create.options">
2931      <title>Database Create Options</title>
2932      <tgroup cols="3">
2933       <colspec colwidth="4*" colname="name"></colspec>
2934       <colspec colwidth="7*" colname="description"></colspec>
2935       <colspec colwidth="3*" colname="default"></colspec>
2936       <thead>
2937        <row>
2938         <entry>Option</entry>
2939         <entry>Description</entry>
2940         <entry>Default</entry>
2941        </row>
2942       </thead>
2943       <tbody>
2944        <row>
2945         <entry>databaseName</entry>
2946         <entry>Database from connection object</entry>
2947         <entry>Default</entry>
2948        </row>
2949       </tbody>
2950      </tgroup>
2951     </table>
2952    </sect2>
2953    <sect2 id="zoom.database.drop">
2954     <title>Database Drop</title>
2955     <para>
2956      For Database Drop, <literal>type</literal> must be set to
2957      <literal>drop</literal> in
2958      <function>ZOOM_package_send</function>.
2959     </para>
2960     <table frame="top" id="zoom.database.drop.options">
2961      <title>Database Drop Options</title>
2962      <tgroup cols="3">
2963       <colspec colwidth="4*" colname="name"></colspec>
2964       <colspec colwidth="7*" colname="description"></colspec>
2965       <colspec colwidth="3*" colname="default"></colspec>
2966       <thead>
2967        <row>
2968         <entry>Option</entry>
2969         <entry>Description</entry>
2970         <entry>Default</entry>
2971        </row>
2972       </thead>
2973       <tbody>
2974        <row>
2975         <entry>databaseName</entry>
2976         <entry>Database from connection object</entry>
2977         <entry>Default</entry>
2978        </row>
2979       </tbody>
2980      </tgroup>
2981     </table>
2982    </sect2>
2983    <sect2 id="zoom.commit">
2984     <title>Commit Operation</title>
2985     <para>
2986      For Commit, <literal>type</literal> must be set to
2987      <literal>commit</literal> in
2988      <function>ZOOM_package_send</function>.
2989     </para>
2990    </sect2>
2991    <sect2 id="zoom.extended.services.behavior">
2992     <title>Protocol behavior</title>
2993     <para>
2994      All the extended services are Z39.50-only.
2995     </para>
2996     <note>
2997      <para>
2998       The database create, drop and commit services are privately defined
2999       operations.
3000       Refer to <filename>esadmin.asn</filename> in YAZ for the ASN.1
3001       definitions.
3002      </para>
3003     </note>
3004    </sect2>
3005   </sect1>
3006   <sect1 id="zoom.options">
3007    <title>Options</title>
3008    <para>
3009     Most &zoom; objects provide a way to specify options to change behavior.
3010     From an implementation point of view a set of options is just like
3011     an associative array / hash.
3012    </para>
3013    <synopsis>
3014      ZOOM_options ZOOM_options_create(void);
3015
3016      ZOOM_options ZOOM_options_create_with_parent(ZOOM_options parent);
3017
3018      void ZOOM_options_destroy(ZOOM_options opt);
3019    </synopsis>
3020    <synopsis>
3021      const char *ZOOM_options_get(ZOOM_options opt, const char *name);
3022
3023      void ZOOM_options_set(ZOOM_options opt, const char *name,
3024                            const char *v);
3025    </synopsis>
3026    <synopsis>
3027      typedef const char *(*ZOOM_options_callback)
3028                             (void *handle, const char *name);
3029
3030      ZOOM_options_callback
3031              ZOOM_options_set_callback(ZOOM_options opt,
3032                                        ZOOM_options_callback c,
3033                                        void *handle);
3034    </synopsis>
3035   </sect1>
3036   <sect1 id="zoom.queryconversions">
3037    <title>Query conversions</title>
3038    <synopsis>
3039     int ZOOM_query_cql2rpn(ZOOM_query s, const char *cql_str,
3040                            ZOOM_connection conn);
3041
3042     int ZOOM_query_ccl2rpn(ZOOM_query s, const char *ccl_str,
3043                            const char *config,
3044                            int *ccl_error, const char **error_string,
3045                            int *error_pos);
3046    </synopsis>
3047    <para>
3048     <function>ZOOM_query_cql2rpn</function> translates the CQL string,
3049     client-side, into RPN which may be passed to the server.
3050     This is useful for server's that don't themselves
3051     support CQL, for which <function>ZOOM_query_cql</function> is useless.
3052     `conn' is used  only as a place to stash diagnostics if compilation
3053     fails; if this information is not needed, a null pointer may be used.
3054     The CQL conversion is driven by option <literal>cqlfile</literal> from
3055     connection conn. This specifies a conversion file (eg pqf.properties)
3056     which <emphasis>must</emphasis> be present.
3057    </para>
3058    <para>
3059     <function>ZOOM_query_ccl2rpn</function> translates the CCL string,
3060     client-side, into RPN which may be passed to the server.
3061     The conversion is driven by the specification given by
3062     <literal>config</literal>. Upon completion 0 is returned on success; -1
3063     is returned on on failure. Om failure <literal>error_string</literal> and
3064     <literal>error_pos</literal> holds error message and position of
3065     first error in original CCL string.
3066    </para>
3067   </sect1>
3068   <sect1 id="zoom.events"><title>Events</title>
3069    <para>
3070     If you're developing non-blocking applications, you have to deal
3071     with events.
3072    </para>
3073    <synopsis>
3074     int ZOOM_event(int no, ZOOM_connection *cs);
3075    </synopsis>
3076    <para>
3077     The <function>ZOOM_event</function> executes pending events for
3078     a number of connections. Supply the number of connections in
3079     <literal>no</literal> and an array of connections in
3080     <literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
3081     A pending event could be a sending a search, receiving a response,
3082     etc.
3083     When an event has occurred for one of the connections, this function
3084     returns a positive integer <literal>n</literal> denoting that an event
3085     occurred for connection <literal>cs[n-1]</literal>.
3086     When no events are pending for the connections, a value of zero is
3087     returned.
3088     To ensure that all outstanding requests are performed call this function
3089     repeatedly until zero is returned.
3090    </para>
3091    <para>
3092     If <function>ZOOM_event</function> returns and returns non-zero, the
3093     last event that occurred can be expected.
3094    </para>
3095    <synopsis>
3096     int ZOOM_connection_last_event(ZOOM_connection cs);
3097    </synopsis>
3098    <para>
3099     <function>ZOOM_connection_last_event</function> returns an event type
3100     (integer) for the last event.
3101    </para>
3102
3103    <table frame="top" id="zoom.event.ids">
3104     <title>ZOOM Event IDs</title>
3105     <tgroup cols="2">
3106      <colspec colwidth="4*" colname="name"></colspec>
3107      <colspec colwidth="7*" colname="description"></colspec>
3108      <thead>
3109       <row>
3110        <entry>Event</entry>
3111        <entry>Description</entry>
3112       </row>
3113      </thead>
3114      <tbody>
3115       <row>
3116        <entry>ZOOM_EVENT_NONE</entry>
3117        <entry>No event has occurred</entry>
3118       </row>
3119       <row>
3120        <entry>ZOOM_EVENT_CONNECT</entry>
3121        <entry>TCP/IP connect has initiated</entry>
3122       </row>
3123       <row>
3124        <entry>ZOOM_EVENT_SEND_DATA</entry>
3125        <entry>Data has been transmitted (sending)</entry>
3126       </row>
3127       <row>
3128        <entry>ZOOM_EVENT_RECV_DATA</entry>
3129        <entry>Data has been received)</entry>
3130       </row>
3131       <row>
3132        <entry>ZOOM_EVENT_TIMEOUT</entry>
3133        <entry>Timeout</entry>
3134       </row>
3135       <row>
3136        <entry>ZOOM_EVENT_UNKNOWN</entry>
3137        <entry>Unknown event</entry>
3138       </row>
3139       <row>
3140        <entry>ZOOM_EVENT_SEND_APDU</entry>
3141        <entry>An APDU has been transmitted (sending)</entry>
3142       </row>
3143       <row>
3144        <entry>ZOOM_EVENT_RECV_APDU</entry>
3145        <entry>An APDU has been received</entry>
3146       </row>
3147       <row>
3148        <entry>ZOOM_EVENT_RECV_RECORD</entry>
3149        <entry>A result-set record has been received</entry>
3150       </row>
3151       <row>
3152        <entry>ZOOM_EVENT_RECV_SEARCH</entry>
3153        <entry>A search result been received</entry>
3154       </row>
3155      </tbody>
3156     </tgroup>
3157    </table>
3158   </sect1>
3159  </chapter>
3160  <chapter id="server">
3161   <title>Generic server</title>
3162   <sect1 id="server.introduction"><title>Introduction</title>
3163    <para>
3164     If you aren't into documentation, a good way to learn how the
3165     back end interface works is to look at the <filename>backend.h</filename>
3166     file. Then, look at the small dummy-server in
3167     <filename>ztest/ztest.c</filename>. The <filename>backend.h</filename>
3168     file also makes a good reference, once you've chewed your way through
3169     the prose of this file.
3170    </para>
3171    <para>
3172     If you have a database system that you would like to make available by
3173     means of Z39.50 or SRU, &yaz; basically offers your two options. You
3174     can use the APIs provided by the &asn;, &odr;, and &comstack;
3175     modules to
3176     create and decode PDUs, and exchange them with a client.
3177     Using this low-level interface gives you access to all fields and
3178     options of the protocol, and you can construct your server as close
3179     to your existing database as you like.
3180     It is also a fairly involved process, requiring
3181     you to set up an event-handling mechanism, protocol state machine,
3182     etc. To simplify server implementation, we have implemented a compact
3183     and simple, but reasonably full-functioned server-frontend that will
3184     handle most of the protocol mechanics, while leaving you to
3185     concentrate on your database interface.
3186    </para>
3187    <note>
3188     <para>
3189      The backend interface was designed in anticipation of a specific
3190      integration task, while still attempting to achieve some degree of
3191      generality. We realize fully that there are points where the
3192      interface can be improved significantly. If you have specific
3193      functions or parameters that you think could be useful, send us a
3194      mail (or better, sign on to the mailing list referred to in the
3195      top-level README file). We will try to fit good suggestions into future
3196      releases, to the extent that it can be done without requiring
3197      too many structural changes in existing applications.
3198     </para>
3199    </note>
3200    <note>
3201     <para>
3202      The &yaz; server does not support XCQL.
3203      </para>
3204    </note>
3205   </sect1>
3206   <sect1 id="server.frontend">
3207    <title>The Database Frontend</title>
3208    <para>
3209     We refer to this software as a generic database frontend. Your
3210     database system is the <emphasis>backend database</emphasis>, and the
3211     interface between the two is called the <emphasis>backend API</emphasis>.
3212     The backend API consists of a small number of function handlers and
3213     structure definitions. You are required to provide the
3214     <function>main()</function> routine for the server (which can be
3215     quite simple), as well as a set of handlers to match each of the
3216     prototypes.
3217     The interface functions that you write can use any mechanism you like
3218     to communicate with your database system: You might link the whole
3219     thing together with your database application and access it by
3220     function calls; you might use IPC to talk to a database server
3221     somewhere; or you might link with third-party software that handles
3222     the communication for you (like a commercial database client library).
3223     At any rate, the handlers will perform the tasks of:
3224    </para>
3225    <itemizedlist>
3226     <listitem><para>
3227      Initialization.
3228     </para></listitem>
3229     <listitem><para>
3230      Searching.
3231     </para></listitem>
3232     <listitem><para>
3233      Fetching records.
3234     </para></listitem>
3235     <listitem><para>
3236      Scanning the database index (optional - if you wish to implement SCAN).
3237     </para></listitem>
3238     <listitem><para>
3239      Extended Services (optional).
3240     </para></listitem>
3241     <listitem><para>
3242      Result-Set Delete (optional).
3243     </para></listitem>
3244     <listitem><para>
3245      Result-Set Sort (optional).
3246     </para></listitem>
3247     <listitem><para>
3248      Return Explain for SRU (optional).
3249     </para></listitem>
3250    </itemizedlist>
3251    <para>
3252     (more functions will be added in time to support as much of
3253     Z39.50-1995 as possible).
3254    </para>
3255   </sect1>
3256   <sect1 id="server.backend">
3257    <title>The Backend API</title>
3258    <para>
3259     The header file that you need to use the interface are in the
3260     <filename>include/yaz</filename> directory. It's called
3261     <filename>backend.h</filename>. It will include other files from
3262     the <filename>include/yaz</filename> directory, so you'll
3263     probably want to use the -I option of your compiler to tell it
3264     where to find the files. When you run
3265     <literal>make</literal> in the top-level &yaz; directory,
3266     everything you need to create your server is to link with the
3267     <filename>lib/libyaz.la</filename> library.
3268    </para>
3269   </sect1>
3270   <sect1 id="server.main">
3271    <title>Your main() Routine</title>
3272    <para>
3273     As mentioned, your <function>main()</function> routine can be quite brief.
3274     If you want to initialize global parameters, or read global configuration
3275     tables, this is the place to do it. At the end of the routine, you should
3276     call the function
3277    </para>
3278    <synopsis>
3279 int statserv_main(int argc, char **argv,
3280                   bend_initresult *(*bend_init)(bend_initrequest *r),
3281                   void (*bend_close)(void *handle));
3282    </synopsis>
3283    <para>
3284     The third and fourth arguments are pointers to handlers. Handler
3285     <function>bend_init</function> is called whenever the server receives
3286     an Initialize Request, so it serves as a Z39.50 session initializer. The
3287     <function>bend_close</function> handler is called when the session is
3288     closed.
3289    </para>
3290    <para>
3291     <function>statserv_main</function> will establish listening sockets
3292     according to the parameters given. When connection requests are received,
3293     the event handler will typically <function>fork()</function> and
3294     create a sub-process to handle a new connection.
3295     Alternatively the server may be setup to create threads for each
3296     connection.
3297     If you do use global variables and forking, you should be aware, then,
3298     that these cannot be shared between associations, unless you explicitly
3299     disable forking by command line parameters.
3300    </para>
3301    <para>
3302     The server provides a mechanism for controlling some of its behavior
3303     without using command-line options. The function
3304    </para>
3305    <synopsis>
3306     statserv_options_block *statserv_getcontrol(void);
3307    </synopsis>
3308    <para>
3309     will return a pointer to a <literal>struct statserv_options_block</literal>
3310     describing the current default settings of the server. The structure
3311     contains these elements:
3312     <variablelist>
3313      <varlistentry>
3314       <term><literal>int dynamic</literal></term>
3315       <listitem><para>
3316        A boolean value, which determines whether the server
3317        will fork on each incoming request (TRUE), or not (FALSE). Default is
3318        TRUE. This flag is only read by UNIX-based servers (WIN32 based servers
3319        doesn't fork).
3320      </para></listitem>
3321      </varlistentry>
3322      <varlistentry>
3323       <term><literal>int threads</literal></term>
3324       <listitem><para>
3325        A boolean value, which determines whether the server
3326        will create a thread on each incoming request (TRUE), or not (FALSE).
3327        Default is FALSE. This flag is only read by UNIX-based servers
3328        that offer POSIX Threads support.
3329        WIN32-based servers always operate in threaded mode.
3330      </para></listitem>
3331      </varlistentry>
3332      <varlistentry>
3333       <term><literal>int inetd</literal></term>
3334       <listitem><para>
3335        A boolean value, which determines whether the server
3336        will operates under a UNIX INET daemon (inetd). Default is FALSE.
3337      </para></listitem>
3338      </varlistentry>
3339      <varlistentry>
3340       <term><literal>char logfile[ODR_MAXNAME+1]</literal></term>
3341       <listitem><para>File for diagnostic output (&quot;&quot;: stderr).
3342      </para></listitem>
3343      </varlistentry>
3344      <varlistentry>
3345       <term><literal>char apdufile[ODR_MAXNAME+1]</literal></term>
3346       <listitem><para>
3347        Name of file for logging incoming and outgoing APDUs
3348        (&quot;&quot;: don't log APDUs, &quot;-&quot;:
3349        <literal>stderr</literal>).
3350      </para></listitem>
3351      </varlistentry>
3352      <varlistentry>
3353       <term><literal>char default_listen[1024]</literal></term>
3354       <listitem><para>Same form as the command-line specification of
3355       listener address. &quot;&quot;: no default listener address.
3356       Default is to listen at &quot;tcp:@:9999&quot;. You can only
3357       specify one default listener address in this fashion.
3358      </para></listitem>
3359      </varlistentry>
3360      <varlistentry>
3361       <term><literal>enum oid_proto default_proto;</literal></term>
3362       <listitem><para>Either <literal>PROTO_Z3950</literal> or
3363       <literal>PROTO_SR</literal>.
3364       Default is <literal>PROTO_Z39_50</literal>.
3365      </para></listitem>
3366      </varlistentry>
3367      <varlistentry>
3368       <term><literal>int idle_timeout;</literal></term>
3369       <listitem><para>Maximum session idle-time, in minutes. Zero indicates
3370       no (infinite) timeout. Default is 15 minutes.
3371      </para></listitem>
3372      </varlistentry>
3373      <varlistentry>
3374       <term><literal>int maxrecordsize;</literal></term>
3375       <listitem><para>Maximum permissible record (message) size. Default
3376       is 64 MB. This amount of memory will only be allocated if a
3377       client requests a very large amount of records in one operation
3378       (or a big record).
3379       Set it to a lower number if you are worried about resource
3380       consumption on your host system.
3381      </para></listitem>
3382      </varlistentry>
3383      <varlistentry>
3384       <term><literal>char configname[ODR_MAXNAME+1]</literal></term>
3385       <listitem><para>Passed to the backend when a new connection is received.
3386      </para></listitem>
3387      </varlistentry>
3388      <varlistentry>
3389       <term><literal>char setuid[ODR_MAXNAME+1]</literal></term>
3390       <listitem><para>Set user id to the user specified, after binding
3391       the listener addresses.
3392      </para></listitem>
3393      </varlistentry>
3394      <varlistentry>
3395       <term>
3396        <literal>void (*bend_start)(struct statserv_options_block *p)</literal>
3397       </term>
3398       <listitem><para>Pointer to function which is called after the
3399       command line options have been parsed - but before the server
3400       starts listening.
3401       For forked UNIX servers this handler is called in the mother
3402       process; for threaded servers this handler is called in the
3403       main thread.
3404       The default value of this pointer is NULL in which case it
3405       isn't invoked by the frontend server.
3406       When the server operates as an NT service this handler is called
3407       whenever the service is started.
3408       </para></listitem>
3409      </varlistentry>
3410      <varlistentry>
3411       <term>
3412        <literal>void (*bend_stop)(struct statserv_options_block *p)</literal>
3413       </term>
3414       <listitem><para>Pointer to function which is called whenever the server
3415       has stopped listening for incoming connections. This function pointer
3416       has a default value of NULL in which case it isn't called.
3417       When the server operates as an NT service this handler is called
3418       whenever the service is stopped.
3419       </para></listitem>
3420      </varlistentry>
3421      <varlistentry>
3422       <term><literal>void *handle</literal></term>
3423       <listitem><para>User defined pointer (default value NULL).
3424       This is a per-server handle that can be used to specify "user-data".
3425       Do not confuse this with the session-handle as returned by bend_init.
3426       </para></listitem>
3427      </varlistentry>
3428     </variablelist>
3429    </para>
3430    <para>
3431     The pointer returned by <literal>statserv_getcontrol</literal> points to
3432     a static area. You are allowed to change the contents of the structure,
3433     but the changes will not take effect before you call
3434    </para>
3435    <synopsis>
3436 void statserv_setcontrol(statserv_options_block *block);
3437    </synopsis>
3438    <note>
3439     <para>
3440      that you should generally update this structure before calling
3441      <function>statserv_main()</function>.
3442     </para>
3443    </note>
3444   </sect1>
3445   <sect1 id="server.backendfunctions">
3446    <title>The Backend Functions</title>
3447    <para>
3448     For each service of the protocol, the backend interface declares one or
3449     two functions. You are required to provide implementations of the
3450     functions representing the services that you wish to implement.
3451    </para>
3452    <sect2 id="server.init">
3453     <title>Init</title>
3454     <synopsis>
3455 bend_initresult (*bend_init)(bend_initrequest *r);
3456     </synopsis>
3457     <para>
3458      This handler is called once for each new connection request, after
3459      a new process/thread has been created, and an Initialize Request has
3460      been received from the client. The pointer to the
3461      <function>bend_init</function> handler is passed in the call to
3462      <function>statserv_start</function>.
3463     </para>
3464     <para>
3465      This handler is also called when operating in SRU mode - when
3466      a connection has been made (even though SRU does not offer
3467      this service).
3468     </para>
3469     <para>
3470      Unlike previous versions of YAZ, the <function>bend_init</function> also
3471      serves as a handler that defines the Z39.50 services that the backend
3472      wish to support. Pointers to <emphasis>all</emphasis> service handlers,
3473      including search - and fetch must be specified here in this handler.
3474     </para>
3475     <para>
3476      The request - and result structures are defined as
3477     </para>
3478     <synopsis>
3479 typedef struct bend_initrequest
3480 {
3481     /** \brief user/name/password to be read */
3482     Z_IdAuthentication *auth;
3483     /** \brief encoding stream (for results) */
3484     ODR stream;
3485     /** \brief printing stream */
3486     ODR print;
3487     /** \brief decoding stream (use stream for results) */
3488     ODR decode;
3489     /** \brief reference ID */
3490     Z_ReferenceId *referenceId;
3491     /** \brief peer address of client */
3492     char *peer_name;
3493
3494     /** \brief character set and language negotiation
3495
3496     see include/yaz/z-charneg.h
3497     */
3498     Z_CharSetandLanguageNegotiation *charneg_request;
3499
3500     /** \brief character negotiation response */
3501     Z_External *charneg_response;
3502
3503     /** \brief character set (encoding) for query terms
3504
3505     This is NULL by default. It should be set to the native character
3506     set that the backend assumes for query terms */
3507     char *query_charset;
3508
3509     /** \brief whehter query_charset also applies to recors
3510
3511     Is 0 (No) by default. Set to 1 (yes) if records is in the same
3512     character set as queries. If in doubt, use 0 (No).
3513     */
3514     int records_in_same_charset;
3515
3516     char *implementation_id;
3517     char *implementation_name;
3518     char *implementation_version;
3519
3520     /** \brief Z39.50 sort handler */
3521     int (*bend_sort)(void *handle, bend_sort_rr *rr);
3522     /** \brief SRU/Z39.50 search handler */
3523     int (*bend_search)(void *handle, bend_search_rr *rr);
3524     /** \brief SRU/Z39.50 fetch handler */
3525     int (*bend_fetch)(void *handle, bend_fetch_rr *rr);
3526     /** \brief SRU/Z39.50 present handler */
3527     int (*bend_present)(void *handle, bend_present_rr *rr);
3528     /** \brief Z39.50 extended services handler */
3529     int (*bend_esrequest) (void *handle, bend_esrequest_rr *rr);
3530     /** \brief Z39.50 delete result set handler */
3531     int (*bend_delete)(void *handle, bend_delete_rr *rr);
3532     /** \brief Z39.50 scan handler */
3533     int (*bend_scan)(void *handle, bend_scan_rr *rr);
3534     /** \brief Z39.50 segment facility handler */
3535     int (*bend_segment)(void *handle, bend_segment_rr *rr);
3536     /** \brief SRU explain handler */
3537     int (*bend_explain)(void *handle, bend_explain_rr *rr);
3538     /** \brief SRU scan handler */
3539     int (*bend_srw_scan)(void *handle, bend_scan_rr *rr);
3540     /** \brief SRU record update handler */
3541     int (*bend_srw_update)(void *handle, bend_update_rr *rr);
3542
3543     /** \brief whether named result sets are supported (0=disable, 1=enable) */
3544     int named_result_sets;
3545 } bend_initrequest;
3546
3547 typedef struct bend_initresult
3548 {
3549     int errcode;               /* 0==OK */
3550     char *errstring;           /* system error string or NULL */
3551     void *handle;              /* private handle to the backend module */
3552 } bend_initresult;
3553     </synopsis>
3554     <para>
3555      In general, the server frontend expects that the
3556      <literal>bend_*result</literal> pointer that you return is valid at
3557      least until the next call to a <literal>bend_* function</literal>.
3558      This applies to all of the functions described herein. The parameter
3559      structure passed to you in the call belongs to the server frontend, and
3560      you should not make assumptions about its contents after the current
3561      function call has completed. In other words, if you want to retain any
3562      of the contents of a request structure, you should copy them.
3563     </para>
3564     <para>
3565      The <literal>errcode</literal> should be zero if the initialization of
3566      the backend went well. Any other value will be interpreted as an error.
3567      The <literal>errstring</literal> isn't used in the current version, but
3568      one option would be to stick it in the initResponse as a VisibleString.
3569      The <literal>handle</literal> is the most important parameter. It should
3570      be set to some value that uniquely identifies the current session to
3571      the backend implementation. It is used by the frontend server in any
3572      future calls to a backend function.
3573      The typical use is to set it to point to a dynamically allocated state
3574      structure that is private to your backend module.
3575     </para>
3576     <para>
3577      The <literal>auth</literal> member holds the authentication information
3578      part of the Z39.50 Initialize Request. Interpret this if your serves
3579      requires authentication.
3580     </para>
3581     <para>
3582      The members <literal>peer_name</literal>,
3583      <literal>implementation_id</literal>,
3584      <literal>implementation_name</literal> and
3585      <literal>implementation_version</literal> holds
3586      DNS of client, ID of implementor, name
3587      of client (Z39.50) implementation - and version.
3588     </para>
3589     <para>
3590      The <literal>bend_</literal> - members are set to NULL when
3591      <function>bend_init</function> is called. Modify the pointers by
3592      setting them to point to backend functions.
3593     </para>
3594    </sect2>
3595    <sect2 id="server.search.retrieve">
3596     <title>Search and Retrieve</title>
3597     <para>
3598      We now describe the handlers that are required to support search -
3599      and retrieve. You must support two functions - one for search - and one
3600      for fetch (retrieval of one record). If desirable you can provide a
3601      third handler which is called when a present request is received which
3602      allows you to optimize retrieval of multiple-records.
3603     </para>
3604     <synopsis>
3605 int (*bend_search) (void *handle, bend_search_rr *rr);
3606
3607 typedef struct {
3608     char *setname;             /* name to give to this set */
3609     int replace_set;           /* replace set, if it already exists */
3610     int num_bases;             /* number of databases in list */
3611     char **basenames;          /* databases to search */
3612     Z_ReferenceId *referenceId;/* reference ID */
3613     Z_Query *query;            /* query structure */
3614     ODR stream;                /* encode stream */
3615     ODR decode;                /* decode stream */
3616     ODR print;                 /* print stream */
3617
3618     bend_request request;
3619     bend_association association;
3620     int *fd;
3621     int hits;                  /* number of hits */
3622     int errcode;               /* 0==OK */
3623     char *errstring;           /* system error string or NULL */
3624     Z_OtherInformation *search_info; /* additional search info */
3625     char *srw_sortKeys;        /* holds SRU/SRW sortKeys info */
3626     char *srw_setname;         /* holds SRU/SRW generated resultsetID */
3627     int *srw_setnameIdleTime;  /* holds SRU/SRW life-time */
3628     int estimated_hit_count;   /* if hit count is estimated */
3629     int partial_resultset;     /* if result set is partial */
3630 } bend_search_rr;
3631     </synopsis>
3632     <para>
3633      The <function>bend_search</function> handler is a fairly close
3634      approximation of a protocol Z39.50 Search Request - and Response PDUs
3635      The <literal>setname</literal> is the resultSetName from the protocol.
3636      You are required to establish a mapping between the set name and whatever
3637      your backend database likes to use.
3638      Similarly, the <literal>replace_set</literal> is a boolean value
3639      corresponding to the resultSetIndicator field in the protocol.
3640      <literal>num_bases/basenames</literal> is a length of/array of character
3641      pointers to the database names provided by the client.
3642      The <literal>query</literal> is the full query structure as defined in
3643      the protocol ASN.1 specification.
3644      It can be either of the possible query types, and it's up to you to
3645      determine if you can handle the provided query type.
3646      Rather than reproduce the C interface here, we'll refer you to the
3647      structure definitions in the file
3648      <filename>include/yaz/z-core.h</filename>. If you want to look at the
3649      attributeSetId OID of the RPN query, you can either match it against
3650      your own internal tables, or you can use the <link linkend="tools.oid">
3651      OID tools</link>.
3652     </para>
3653     <para>
3654      The structure contains a number of hits, and an
3655      <literal>errcode/errstring</literal> pair. If an error occurs
3656      during the search, or if you're unhappy with the request, you should
3657      set the errcode to a value from the BIB-1 diagnostic set. The value
3658      will then be returned to the user in a nonsurrogate diagnostic record
3659      in the response. The <literal>errstring</literal>, if provided, will
3660      go in the addinfo field. Look at the protocol definition for the
3661      defined error codes, and the suggested uses of the addinfo field.
3662     </para>
3663     <para>
3664      The <function>bend_search</function> handler is also called when
3665      the frontend server receives a SRU SearchRetrieveRequest.
3666      For SRU, a CQL query is usually provided by the client.
3667      The CQL query is available as part of <literal>Z_Query</literal>
3668      structure (note that CQL is now part of Z39.50 via an external).
3669      To support CQL in existing implementations that only do Type-1,
3670      we refer to the CQL-to-PQF tool described
3671      <link linkend="cql.to.pqf">here</link>.
3672     </para>
3673     <para>
3674      To maintain backwards compatibility, the frontend server
3675      of yaz always assume that error codes are BIB-1 diagnostics.
3676      For SRU operation, a Bib-1 diagnostic code is mapped to
3677      SRU diagnostic.
3678     </para>
3679     <synopsis>
3680 int (*bend_fetch) (void *handle, bend_fetch_rr *rr);
3681
3682 typedef struct bend_fetch_rr {
3683     char *setname;             /* set name */
3684     int number;                /* record number */
3685     Z_ReferenceId *referenceId;/* reference ID */
3686     Odr_oid *request_format;        /* format, transfer syntax (OID) */
3687     Z_RecordComposition *comp; /* Formatting instructions */
3688     ODR stream;                /* encoding stream - memory source if req */
3689     ODR print;                 /* printing stream */
3690
3691     char *basename;            /* name of database that provided record */
3692     int len;                   /* length of record or -1 if structured */
3693     char *record;              /* record */
3694     int last_in_set;           /* is it?  */
3695     Odr_oid *output_format;        /* response format/syntax (OID) */
3696     int errcode;               /* 0==success */
3697     char *errstring;           /* system error string or NULL */
3698     int surrogate_flag;        /* surrogate diagnostic */
3699     char *schema;              /* string record schema input/output */
3700 } bend_fetch_rr;
3701     </synopsis>
3702     <para>
3703      The frontend server calls the <function>bend_fetch</function> handler
3704      when it needs database records to fulfill a Z39.50 Search Request, a
3705      Z39.50 Present Request or a SRU SearchRetrieveRequest.
3706      The <literal>setname</literal> is simply the name of the result set
3707      that holds the reference to the desired record.
3708      The <literal>number</literal> is the offset into the set (with 1
3709      being the first record in the set). The <literal>format</literal> field
3710      is the record format requested by the client (See
3711      <xref linkend="tools.oid"/>).
3712      A value of NULL for <literal>format</literal> indicates that the
3713      client did not request a specific format.
3714      The <literal>stream</literal> argument is an &odr; stream which
3715      should be used for allocating space for structured data records.
3716      The stream will be reset when all records have been assembled, and
3717      the response package has been transmitted.
3718      For unstructured data, the backend is responsible for maintaining a
3719      static or dynamic buffer for the record between calls.
3720     </para>
3721     <para>
3722      If a SRU SearchRetrieveRequest is received by the frontend server,
3723      the <literal>referenceId</literal> is NULL and the
3724      <literal>format</literal> (transfer syntax) is the OID for XML.
3725      The schema for SRU is stored in both the
3726      <literal>Z_RecordComposition</literal>
3727      structure and <literal>schema</literal> (simple string).
3728     </para>
3729     <para>
3730      In the structure, the <literal>basename</literal> is the name of the
3731      database that holds the
3732      record. <literal>len</literal> is the length of the record returned, in
3733      bytes, and <literal>record</literal> is a pointer to the record.
3734      <literal>last_in_set</literal> should be nonzero only if the record
3735      returned is the last one in the given result set.
3736      <literal>errcode</literal> and <literal>errstring</literal>, if
3737      given, will be interpreted as a global error pertaining to the
3738      set, and will be returned in a non-surrogate-diagnostic.
3739      If you wish to return the error as a surrogate-diagnostic
3740      (local error) you can do this by setting
3741      <literal>surrogate_flag</literal> to 1 also.
3742     </para>
3743     <para>
3744      If the <literal>len</literal> field has the value -1, then
3745      <literal>record</literal> is assumed to point to a constructed data
3746      type. The <literal>format</literal> field will be used to determine
3747      which encoder should be used to serialize the data.
3748     </para>
3749     <note>
3750      <para>
3751       If your backend generates structured records, it should use
3752       <function>odr_malloc()</function> on the provided stream for allocating
3753       data: This allows the frontend server to keep track of the record sizes.
3754      </para>
3755     </note>
3756     <para>
3757      The <literal>format</literal> field is mapped to an object identifier
3758      in the direct reference of the resulting EXTERNAL representation
3759      of the record.
3760     </para>
3761     <note>
3762      <para>
3763       The current version of &yaz; only supports the direct reference mode.
3764      </para>
3765     </note>
3766     <synopsis>
3767 int (*bend_present) (void *handle, bend_present_rr *rr);
3768
3769 typedef struct {
3770     char *setname;             /* set name */
3771     int start;
3772     int number;                /* record number */
3773     Odr_oid *format;           /* format, transfer syntax (OID) */
3774     Z_ReferenceId *referenceId;/* reference ID */
3775     Z_RecordComposition *comp; /* Formatting instructions */
3776     ODR stream;                /* encoding stream - memory source if required */
3777     ODR print;                 /* printing stream */
3778     bend_request request;
3779     bend_association association;
3780
3781     int hits;                  /* number of hits */
3782     int errcode;               /* 0==OK */
3783     char *errstring;           /* system error string or NULL */
3784 } bend_present_rr;
3785     </synopsis>
3786     <para>
3787      The <function>bend_present</function> handler is called when
3788      the server receives a Z39.50 Present Request.
3789      The <literal>setname</literal>,
3790      <literal>start</literal> and <literal>number</literal> is the
3791      name of the result set - start position - and number of records to
3792      be retrieved respectively. <literal>format</literal> and
3793      <literal>comp</literal> is the preferred transfer syntax and element
3794      specifications of the present request.
3795     </para>
3796     <para>
3797      Note that this is handler serves as a supplement for
3798      <function>bend_fetch</function> and need not to be defined in order to
3799      support search - and retrieve.
3800     </para>
3801    </sect2>
3802    <sect2 id="server.delete">
3803     <title>Delete</title>
3804     <para>
3805      For back-ends that supports delete of a result set only one handler
3806      must be defined.
3807     </para>
3808     <synopsis>
3809 int (*bend_delete)(void *handle, bend_delete_rr *rr);
3810
3811 typedef struct bend_delete_rr {
3812     int function;
3813     int num_setnames;
3814     char **setnames;
3815     Z_ReferenceId *referenceId;
3816     int delete_status;      /* status for the whole operation */
3817     int *statuses;          /* status each set - indexed as setnames */
3818     ODR stream;
3819     ODR print;
3820 } bend_delete_rr;
3821     </synopsis>
3822     <note>
3823      <para>
3824       The delete set function definition is rather primitive, mostly because
3825       we have had no practical need for it as of yet. If someone wants
3826       to provide a full delete service, we'd be happy to add the
3827       extra parameters that are required. Are there clients out there
3828       that will actually delete sets they no longer need?
3829      </para>
3830     </note>
3831    </sect2>
3832    <sect2 id="server.scan">
3833     <title>Scan</title>
3834     <para>
3835      For servers that wish to offer the scan service one handler
3836      must be defined.
3837     </para>
3838     <synopsis>
3839 int (*bend_scan)(void *handle, bend_scan_rr *rr);
3840
3841 typedef enum {
3842     BEND_SCAN_SUCCESS,  /* ok */
3843     BEND_SCAN_PARTIAL   /* not all entries could be found */
3844 } bend_scan_status;
3845
3846 typedef struct bend_scan_rr {
3847     int num_bases;      /* number of elements in databaselist */
3848     char **basenames;   /* databases to search */
3849     Odr_oid *attributeset;
3850     Z_ReferenceId *referenceId; /* reference ID */
3851     Z_AttributesPlusTerm *term;
3852     ODR stream;         /* encoding stream - memory source if required */
3853     ODR print;          /* printing stream */
3854
3855     int *step_size;     /* step size */
3856     int term_position;  /* desired index of term in result list/returned */
3857     int num_entries;    /* number of entries requested/returned */
3858
3859     /* scan term entries. The called handler does not have
3860        to allocate this. Size of entries is num_entries (see above) */
3861     struct scan_entry *entries;
3862     bend_scan_status status;
3863     int errcode;
3864     char *errstring;
3865     char *scanClause;   /* CQL scan clause */
3866     char *setname;      /* Scan in result set (NULL if omitted) */
3867 } bend_scan_rr;
3868     </synopsis>
3869    <para>
3870     This backend server handles both Z39.50 scan
3871     and SRU scan. In order for a handler to distinguish between SRU (CQL) scan
3872     Z39.50 Scan , it must check for a non-NULL value of
3873     <literal>scanClause</literal>.
3874    </para>
3875    <note>
3876     <para>
3877      if designed today, it would be a choice using a union or similar,
3878      but that would break binary compatibility with existing servers.
3879     </para>
3880     </note>
3881    </sect2>
3882   </sect1>
3883   <sect1 id="server.invocation">
3884    <title>Application Invocation</title>
3885    <para>
3886     The finished application has the following
3887     invocation syntax (by way of <function>statserv_main()</function>):
3888    </para>
3889    &gfs-synopsis;
3890    <para>
3891     The options are:
3892     &gfs-options;
3893    </para>
3894    <para>
3895     A listener specification consists of a transport mode followed by a
3896     colon (:) followed by a listener address. The transport mode is
3897     either <literal>tcp</literal>, <literal>unix:</literal> or
3898     <literal>ssl</literal>.
3899    </para>
3900    <para>
3901     For TCP and SSL, an address has the form
3902    </para>
3903    <synopsis>
3904     hostname | IP-number [: portnumber]
3905    </synopsis>
3906    <para>
3907     The port number defaults to 210 (standard Z39.50 port).
3908    </para>
3909    <para>
3910     For UNIX, the address is the filename of socket.
3911    </para>
3912    <para>
3913     For TCP/IP and SSL, the special hostnames <literal>@</literal>,
3914     maps to <literal>IN6ADDR_ANY_INIT</literal> with
3915     IPV4 binding as well (bindv6only=0),
3916     The special hostname <literal>@4</literal> binds to
3917     <literal>INADDR_ANY</literal> (IPV4 only listener).
3918     The special hostname <literal>@6</literal> binds to
3919     <literal>IN6ADDR_ANY_INIT</literal> with bindv6only=1 (IPV6 only listener).
3920    </para>
3921    <example id="server.example.running.unix">
3922     <title>Running the GFS on Unix</title>
3923     <para>
3924      Assuming the server application <replaceable>appname</replaceable> is
3925      started as root, the following will make it listen on port 210.
3926      The server will change identity to <literal>nobody</literal>
3927      and write its log to <filename>/var/log/app.log</filename>.
3928      <screen>
3929       application -l /var/log/app.log -u nobody tcp:@:210
3930      </screen>
3931     </para>
3932     <para>
3933      The server will accept Z39.50 requests and offer SRU service on port 210.
3934     </para>
3935    </example>
3936    <example id="server.example.apache.sru">
3937     <title>Setting up Apache as SRU Frontend</title>
3938     <para>
3939      If you use <ulink url="&url.apache;">Apache</ulink>
3940      as your public web server and want to offer HTTP port 80
3941      access to the YAZ server on 210, you can use the
3942      <ulink url="&url.apache.directive.proxypass;">
3943       <literal>ProxyPass</literal></ulink>
3944      directive.
3945      If you have virtual host
3946      <literal>srw.mydomain</literal> you can use the following directives
3947      in Apache's httpd.conf:
3948      <screen>
3949       &lt;VirtualHost *>
3950        ErrorLog /home/srw/logs/error_log
3951        TransferLog /home/srw/logs/access_log
3952        ProxyPass / http://srw.mydomain:210/
3953       &lt;/VirtualHost>
3954      </screen>
3955     </para>
3956     <para>
3957      The above for the Apache 1.3 series.
3958     </para>
3959    </example>
3960    <example id="server.example.local.access">
3961     <title>Running a server with local access only</title>
3962     <para>
3963      Servers that is only being accessed from the local host should listen
3964      on UNIX file socket rather than a Internet socket. To listen on
3965      <filename>/tmp/mysocket</filename> start the server as follows:
3966      <screen>
3967       application unix:/tmp/mysocket
3968      </screen>
3969     </para>
3970    </example>
3971   </sect1>
3972   <sect1 id="server.vhosts">
3973    <title>GFS Configuration and Virtual Hosts</title>
3974    &gfs-virtual;
3975   </sect1>
3976  </chapter>
3977  <chapter id="asn">
3978   <title>The Z39.50 ASN.1 Module</title>
3979   <sect1 id="asn.introduction">
3980    <title>Introduction</title>
3981    <para>
3982     The &asn; module provides you with a set of C struct definitions for the
3983     various PDUs of the Z39.50 protocol, as well as for the complex types
3984     appearing within the PDUs. For the primitive data types, the C
3985     representation often takes the form of an ordinary C language type,
3986     such as <literal>Odr_int</literal> which is equivalent to an integral
3987     C integer. For ASN.1 constructs that have no direct
3988     representation in C, such as general octet strings and bit strings,
3989     the &odr; module (see section <link linkend="odr">The ODR Module</link>)
3990     provides auxiliary definitions.
3991    </para>
3992    <para>
3993     The &asn; module is located in sub directory <filename>z39.50</filename>.
3994     There you'll find C files that implements encoders and decoders for the
3995     Z39.50 types. You'll also find the protocol definitions:
3996     <filename>z3950v3.asn</filename>, <filename>esupdate.asn</filename>,
3997     and others.
3998    </para>
3999   </sect1>
4000   <sect1 id="asn.preparing">
4001    <title>Preparing PDUs</title>
4002    <para>
4003     A structure representing a complex ASN.1 type doesn't in itself contain the
4004     members of that type. Instead, the structure contains
4005     <emphasis>pointers</emphasis> to the members of the type.
4006     This is necessary, in part, to allow a mechanism for specifying which
4007     of the optional structure (SEQUENCE) members are present, and which
4008     are not. It follows that you will need to somehow provide space for
4009     the individual members of the structure, and set the pointers to
4010     refer to the members.
4011    </para>
4012    <para>
4013     The conversion routines don't care how you allocate and maintain your
4014     C structures - they just follow the pointers that you provide.
4015     Depending on the complexity of your application, and your personal
4016     taste, there are at least three different approaches that you may take
4017     when you allocate the structures.
4018    </para>
4019    <para>
4020     You can use static or automatic local variables in the function that
4021     prepares the PDU. This is a simple approach, and it provides the most
4022     efficient form of memory management. While it works well for flat
4023     PDUs like the InitReqest, it will generally not be sufficient for say,
4024     the generation of an arbitrarily complex RPN query structure.
4025    </para>
4026    <para>
4027     You can individually create the structure and its members using the
4028     <function>malloc(2)</function> function. If you want to ensure that
4029     the data is freed when it is no longer needed, you will have to
4030     define a function that individually releases each member of a
4031     structure before freeing the structure itself.
4032    </para>
4033    <para>
4034     You can use the <function>odr_malloc()</function> function (see
4035     <xref linkend="odr.use"/> for details). When you use
4036     <function>odr_malloc()</function>, you can release all of the
4037     allocated data in a single operation, independent of any pointers and
4038     relations between the data. <function>odr_malloc()</function> is based on a
4039     &quot;nibble-memory&quot;
4040     scheme, in which large portions of memory are allocated, and then
4041     gradually handed out with each call to <function>odr_malloc()</function>.
4042     The next time you call <function>odr_reset()</function>, all of the
4043     memory allocated since the last call is recycled for future use (actually,
4044     it is placed on a free-list).
4045    </para>
4046    <para>
4047     You can combine all of the methods described here. This will often be
4048     the most practical approach. For instance, you might use
4049     <function>odr_malloc()</function> to allocate an entire structure and
4050     some of its elements, while you leave other elements pointing to global
4051     or per-session default variables.
4052    </para>
4053    <para>
4054     The &asn; module provides an important aid in creating new PDUs. For
4055     each of the PDU types (say, <function>Z_InitRequest</function>), a
4056     function is provided that allocates and initializes an instance of
4057     that PDU type for you. In the case of the InitRequest, the function is
4058     simply named <function>zget_InitRequest()</function>, and it sets up
4059     reasonable default value for all of the mandatory members. The optional
4060     members are generally initialized to null pointers. This last aspect
4061     is very important: it ensures that if the PDU definitions are
4062     extended after you finish your implementation (to accommodate
4063     new versions of the protocol, say), you won't get into trouble with
4064     uninitialized pointers in your structures. The functions use
4065     <function>odr_malloc()</function> to
4066     allocate the PDUs and its members, so you can free everything again with a
4067     single call to <function>odr_reset()</function>. We strongly recommend
4068     that you use the <literal>zget_*</literal>
4069     functions whenever you are preparing a PDU (in a C++ API, the
4070     <literal>zget_</literal>
4071     functions would probably be promoted to constructors for the
4072     individual types).
4073    </para>
4074    <para>
4075    The prototype for the individual PDU types generally look like this:
4076    </para>
4077    <synopsis>