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