doc/book.xml

   1 <?xml version="1.0" standalone="no"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   3     "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
   4 [
   5      <!ENTITY % local SYSTEM "local.ent">
   6      %local;
   7      <!ENTITY % entities SYSTEM "entities.ent">
   8      %entities;
   9      <!ENTITY % idcommon SYSTEM "common/common.ent">
  10      %idcommon;
  11 ]>
  12 <book>
  13  <bookinfo>
  14   <title>YAZ User&apos;s Guide and Reference</title>
  15   <authorgroup>
  16    <author><firstname>Sebastian</firstname><surname>Hammer</surname></author>
  17    <author><firstname>Adam</firstname><surname>Dickmeiss</surname></author>
  18    <author><firstname>Mike</firstname><surname>Taylor</surname></author>
  19    <author><firstname>Heikki</firstname><surname>Levanto</surname></author>
  20    <author><firstname>Dennis</firstname><surname>Schafroth</surname></author>
  21   </authorgroup>
  22   <releaseinfo>&version;</releaseinfo>
  23   <copyright>
  24    <year>&copyright-year;</year>
  25    <holder>Index Data</holder>
  26   </copyright>
  27   <abstract>
  28    <simpara>
  29     This document is the programmer's guide and reference to the &yaz;
  30     package version &version;. &yaz; is a compact toolkit that provides
  31     access to the Z39.50 and SRU/Solr protocols, as well as a set of
  32     higher-level tools for implementing the server and client
  33     roles, respectively.
  34     The documentation can be used on its own, or as a reference when
  35     looking at the example applications provided with the package.
  36    </simpara>
  37    <simpara>
  38     <inlinemediaobject>
  39      <imageobject>
  40       <imagedata fileref="common/id.png" format="PNG"/>
  41      </imageobject>
  42      <imageobject>
  43       <imagedata fileref="common/id.eps" format="EPS"/>
  44      </imageobject>
  45     </inlinemediaobject>
  46    </simpara></abstract>
  47  </bookinfo>
  48  <chapter id="introduction">
  49   <title>Introduction</title>
  50   <para>
  51    &yaz; is a C/C++ library for information retrieval applications
  52    using the Z39.50/SRU/Solr protocols for information retrieval.
  53   </para>
  54   <para>
  55    Properties of &yaz;:
  56    <itemizedlist>
  57     <listitem>
  58      <para>
  59       Complete
  60       <ulink url="&url.z39.50;">Z39.50</ulink> version 3 support.
  61       Amendments and Z39.50-2002 revision is supported.
  62     </para>
  63     </listitem>
  64     <listitem>
  65      <para>
  66       Supports
  67       <ulink url="&url.sru;">SRU GET/POST/SOAP</ulink>
  68       version 1.1, 1.2 and 2.0 (over HTTP and HTTPS).
  69     </para>
  70     </listitem>
  71     <listitem>
  72      <para>
  73       Includes BER encoders/decoders for the
  74       <ulink url="&url.ill;">ISO ILL</ulink>
  75       protocol.
  76     </para>
  77     </listitem>
  78     <listitem>
  79      <para>
  80       Supports
  81       <ulink url="&url.solr;">Solr</ulink> Web Service version 1.4.x
  82       (client side only)
  83      </para>
  84     </listitem>
  85     <listitem>
  86      <para>
  87       Supports the following transports: BER over TCP/IP
  88       (<ulink url="&url.ber.over.tcpip;">RFC1729</ulink>),
  89       BER over unix local socket, and
  90       <ulink url="&url.http.1.1;">HTTP 1.1</ulink>.
  91     </para>
  92     </listitem>
  93     <listitem>
  94      <para>
  95       Secure Socket Layer support using
  96       <ulink url="&url.gnutls;">GnuTLS</ulink>.
  97       If enabled, &yaz; uses HTTPS transport (for SOAP) or
  98       "Secure BER" (for Z39.50).
  99      </para>
 100     </listitem>
 101     <listitem>
 102      <para>
 103       Offers
 104       <ulink url="&url.zoom;">ZOOM</ulink> C API implementing
 105       Z39.50, SRU and Solr Web Service.
 106     </para>
 107     </listitem>
 108     <listitem>
 109      <para>
 110       The &yaz; library offers a set of useful utilities
 111       related to the protocols, such as MARC (ISO2709) parser,
 112       CCL (ISO8777) parser,
 113       <ulink url="&url.cql;">CQL</ulink>
 114       parser, memory management routines, character set conversion.
 115      </para>
 116     </listitem>
 117     <listitem>
 118      <para>
 119       Portable code. &yaz; compiles out-of-the box on most Unixes and
 120       on Windows using Microsoft Visual C++.
 121      </para>
 122     </listitem>
 123     <listitem>
 124      <para>
 125       Fast operation. The C based BER encoders/decoders as well
 126       as the server component of &yaz; is very fast.
 127     </para>
 128     </listitem>
 129     <listitem>
 130      <para>
 131       Liberal license that allows for commercial use of &yaz;.
 132      </para>
 133     </listitem>
 134    </itemizedlist>
 135   </para>
 136
 137   <sect1 id="introduction.reading">
 138    <title>Reading this Manual</title>
 139    <para>
 140     Most implementors only need to read a fraction of the
 141     material in thie manual, so a quick walkthrough of the chapters
 142     is in order.
 143    </para>
 144    <itemizedlist>
 145     <listitem>
 146      <para>
 147       <xref linkend="installation"/> contains installation
 148       instructions for &yaz;. You don't need reading this
 149       if you expect to download &yaz; binaries.
 150       However, the chapter contains information about how
 151       to make <emphasis>your</emphasis> application link
 152       with &yaz;.
 153      </para>
 154     </listitem>
 155     <listitem>
 156      <para>
 157       <xref linkend="zoom"/> describes the ZOOM API of &yaz;.
 158       This is definitely worth a read if you wish to develop a Z39.50/SRU
 159       client.
 160      </para>
 161     </listitem>
 162     <listitem>
 163      <para>
 164       <xref linkend="server"/> describes the generic frontend server
 165       and explains how to develop server Z39.50/SRU applications for &yaz;.
 166       Obviously worth reading if you're to develop a server.
 167     </para>
 168     </listitem>
 169     <listitem>
 170      <para>
 171       <xref linkend="yaz-client"/> describes how to use the &yaz; Z39.50
 172       client. If you're developer and wish to test your server
 173       or a server from another party, you might find this chapter
 174       useful.
 175     </para>
 176     </listitem>
 177     <listitem>
 178      <para>
 179       <xref linkend="asn"/> documents the most commonly used Z39.50
 180       C data structures offered by the &yaz; API. Client
 181       developers using ZOOM and non-Z39.50 implementors may skip this.
 182      </para>
 183     </listitem>
 184     <listitem>
 185      <para>
 186       <xref linkend="soap"/> describes how SRU and SOAP is used
 187       in &yaz;. Only if you're developing SRU applications
 188       this section is a must.
 189      </para>
 190     </listitem>
 191     <listitem>
 192      <para>
 193       <xref linkend="tools"/> contains sections for the various
 194       tools offered by &yaz;. Scan through the material quickly
 195       and see what's relevant to you! SRU implementors
 196       might find the <link linkend="cql">CQL</link> section
 197       particularly useful.
 198      </para>
 199     </listitem>
 200     <listitem>
 201      <para>
 202       <xref linkend="odr"/> goes through the details of the
 203       ODR module which is the work horse that encodes and decodes
 204       BER packages. Implementors using ZOOM only, do <emphasis>not</emphasis>
 205       need reading this.
 206       Most other Z39.50 implementors only need to read the first two
 207       sections (<xref linkend="odr.introduction"/> and
 208       <xref linkend="odr.use"/>).
 209      </para>
 210     </listitem>
 211     <listitem>
 212      <para>
 213       <xref linkend="comstack"/> describes the network layer module
 214       COMSTACK. Implementors using ZOOM or the generic frontend server
 215       may skip this. Others, presumably, handling client/server
 216      communication on their own should read this.
 217      </para>
 218     </listitem>
 219    </itemizedlist>
 220   </sect1>
 221   <sect1 id="introduction.api">
 222    <title>The API</title>
 223    <para>
 224     The <ulink url="&url.yaz;">&yaz;</ulink>
 225     toolkit offers several different levels of access to the
 226     <ulink url="&url.z39.50;">ISO23950/Z39.50</ulink>,
 227     <ulink url="&url.ill;">ILL</ulink> and
 228     <ulink url="&url.sru;">SRU</ulink>
 229     protocols.
 230     The level that you need to use depends on your requirements, and
 231     the role (server or client) that you want to implement.
 232     If you're developing a client application you should consider the
 233     <link linkend="zoom">ZOOM</link> API.
 234     It is, by far, the easiest way to develop clients in C.
 235     Server implementers should consider the
 236     <link linkend="server">generic frontend server</link>.
 237     None of those high-level APIs support the whole protocol, but
 238     they do include most facilities used in existing Z39.50 applications.
 239    </para>
 240    <para>
 241     If you're using 'exotic' functionality (meaning anything not included in
 242     the high-level APIs), developing non-standard extensions to Z39.50 or
 243     you're going to develop an ILL application you'll have to learn the lower
 244     level APIs of &yaz;.
 245    </para>
 246    <para>
 247     The YAZ toolkit modules is shown in figure <xref linkend="yaz.layer"/>.
 248    </para>
 249    <figure id="yaz.layer">
 250     <title>YAZ layers</title>
 251     <mediaobject>
 252      <imageobject>
 253       <imagedata fileref="apilayer.png" format="PNG"/>
 254      </imageobject>
 255      <imageobject>
 256       <imagedata fileref="apilayer.eps" format="EPS"/>
 257      </imageobject>
 258     </mediaobject>
 259    </figure>
 260    <para>
 261     There are four layers.
 262     <itemizedlist>
 263      <listitem>
 264       <para>A client or server application (or both).
 265        This layer includes ZOOM and the generic frontend server.
 266       </para>
 267      </listitem>
 268      <listitem>
 269       <para>
 270        The second layer provides a C represenation of the
 271        protocol units (packages) for Z39.50 ASN.1, ILL ASN.1,
 272        SRU.
 273       </para>
 274      </listitem>
 275      <listitem>
 276       <para>
 277        The third layer encodes and decodes protocol data units to
 278        simple packages (buffer with certain length). The &odr; module
 279        encodes and decodes BER whereas the HTTP modules encodes and
 280        decodes HTTP ruquests/responses.
 281       </para>
 282      </listitem>
 283      <listitem>
 284       <para>
 285        The lowest layer is &comstack; which exchanges the encoded packages
 286        with a peer process over a network.
 287       </para>
 288      </listitem>
 289     </itemizedlist>
 290    </para>
 291    <para>
 292     The &asn; module represents the ASN.1 definition of
 293     the Z39.50 protocol. It establishes a set of type and
 294     structure definitions, with one structure for each of the top-level
 295     PDUs, and one structure or type for each of the contained ASN.1 types.
 296     For primitive types, or other types that are defined by the ASN.1
 297     standard itself (such as the EXTERNAL type), the C representation is
 298     provided by the &odr; (Open Data Representation) subsystem.
 299   </para>
 300    <para>
 301      &odr; is a basic mechanism for representing an
 302     ASN.1 type in the C programming language, and for implementing BER
 303     encoders and decoders for values of that type. The types defined in
 304     the &asn; module generally have the prefix <literal>Z_</literal>, and
 305     a suffix corresponding to the name of the type in the ASN.1
 306     specification of the protocol (generally Z39.50-1995). In the case of
 307     base types (those originating in the ASN.1 standard itself), the prefix
 308     <literal>Odr_</literal> is sometimes seen. Either way, look for
 309     the actual definition in either <filename>z-core.h</filename> (for the types
 310     from the protocol), <filename>odr.h</filename> (for the primitive ASN.1
 311     types).
 312     The &asn; library also provides functions (which are, in turn,
 313     defined using &odr; primitives) for encoding and decoding data values.
 314     Their general form is
 315     <funcsynopsis>
 316      <funcprototype><funcdef>int <function>z_<replaceable>xxx</replaceable></function></funcdef>
 317       <paramdef>ODR <parameter>o</parameter></paramdef>
 318       <paramdef>Z_<replaceable>xxx</replaceable> **<parameter>p</parameter></paramdef>
 319       <paramdef>int <parameter>optional</parameter></paramdef>
 320       <paramdef>const char *<parameter>name</parameter></paramdef>
 321      </funcprototype>
 322     </funcsynopsis>
 323     (note the lower-case &quot;z&quot; in the function name)
 324    </para>
 325    <note>
 326     <para>
 327      If you are using the premade definitions of the &asn; module, and you
 328      are not adding new protocol of your own, the only parts of &odr; that you
 329      need to worry about are documented in
 330      <xref linkend="odr.use"/>.
 331     </para>
 332    </note>
 333    <para>
 334     When you have created a BER-encoded buffer, you can use the &comstack;
 335     subsystem to transmit (or receive) data over the network. The &comstack;
 336     module provides simple functions for establishing a connection
 337     (passively or actively, depending on the role of your application),
 338     and for exchanging BER-encoded PDUs over that connection. When you
 339     create a connection endpoint, you need to specify what transport to
 340     use (TCP/IP, SSL or UNIX sockets).
 341     For the remainder of the connection's lifetime, you don't have
 342     to worry about the underlying transport protocol at all - the &comstack;
 343     will ensure that the correct mechanism is used.
 344    </para>
 345    <para>
 346     We call the combined interfaces to &odr;, &asn;, and &comstack; the service
 347     level API. It's the API that most closely models the Z39.50
 348     service/protocol definition, and it provides unlimited access to all
 349     fields and facilities of the protocol definitions.
 350    </para>
 351    <para>
 352     The reason that the &yaz; service-level API is a conglomerate of the
 353     APIs from three different submodules is twofold. First, we wanted to allow
 354     the user a choice of different options for each major task. For instance,
 355     if you don't like the protocol API provided by &odr;/&asn;, you
 356     can use SNACC or BERUtils instead, and still have the benefits of the
 357     transparent transport approach of the &comstack; module. Secondly,
 358     we realize that you may have to fit the toolkit into an existing
 359     event-processing structure, in a way that is incompatible with
 360     the &comstack; interface or some other part of &yaz;.
 361    </para>
 362   </sect1>
 363  </chapter>
 364  <chapter id="installation">
 365   <title>Compilation and Installation</title>
 366   <sect1 id="installation-introduction">
 367    <title>Introduction</title>
 368    <para>
 369     The latest version of the software will generally be found at:
 370    </para>
 371    <para>
 372     <ulink url="&url.yaz.download;"/>
 373    </para>
 374    <para>
 375     We have tried our best to keep the software portable, and on many
 376     platforms, you should be able to compile everything with little or
 377     no changes.
 378    </para>
 379    <para>
 380     The software is regularly tested on
 381     <ulink url="&url.debian;">Debian GNU/Linux</ulink>,
 382     <ulink url="&url.centos;">CentOS</ulink>,
 383     <ulink url="&url.ubuntu;">Ubuntu Linux</ulink>,
 384     <ulink url="&url.freebsd;">FreeBSD (i386)</ulink>,
 385     <ulink url="&url.macosx;">MAC OSX</ulink>,
 386     <ulink url="&url.solaris;">Solaris</ulink>,
 387     Windows 7, Windows XP.
 388    </para>
 389    <para>
 390     Some versions have be known to work on HP/UX,
 391     DEC Unix, <ulink url="&url.netbsd;">NetBSD</ulink>,
 392     <ulink url="&url.openbsd;">OpenBSD</ulink>,
 393     IBM AIX,
 394     Data General DG/UX (with some CFLAGS tinkering),
 395     SGI/IRIX, DDE Supermax, Apple Macintosh (using the Codewarrior programming
 396     environment and the GUSI socket libraries),
 397     IBM AS/400 .
 398    </para>
 399    <para>
 400     If you move the software to other platforms, we'd be grateful if you'd
 401     let us know about it. If you run into difficulties, we will try to help
 402     if we can, and if you solve the problems, we would be happy to include
 403     your fixes in the next release. So far, we have mostly avoided
 404     <literal>#ifdefs</literal> for individual platforms, and we'd
 405     like to keep it that way as far as it makes sense.
 406    </para>
 407    <para>
 408     We maintain a mailing-list for the purpose of announcing new releases and
 409     bug-fixes, as well as general discussion. Subscribe by
 410     filling-in the form
 411     <ulink url="&url.yaz.mailinglist;">here</ulink>.
 412     General questions and problems can be directed at
 413     <ulink url="&url.yaz.mail;"/>, or the address given at the top of
 414      this document.
 415    </para>
 416   </sect1>
 417   <sect1 id="installation.unix"><title>UNIX</title>
 418    <para>
 419     We provide
 420     <ulink url="&url.debian;">Debian GNU/Linux</ulink> (i386 and amd64),
 421     <ulink url="&url.ubuntu;">Ubuntu</ulink> (i386 and amd64)
 422     and
 423     <ulink url="&url.centos;">CentOS</ulink> (amd64 only) packages for &yaz;.
 424     You should be able to create packages for other CPUs by building
 425     them from the source package.
 426    </para>
 427    <para>
 428     YAZ is also part of several packages repositories. Some of them are
 429    </para>
 430    <itemizedlist>
 431     <listitem>
 432      <para>
 433       Solaris CSW: <ulink url="http://www.opencsw.org/packages/yaz/"/>
 434      </para>
 435     </listitem>
 436     <listitem>
 437      <para>
 438       Solaris: <ulink url="http://unixpackages.com"/>
 439      </para>
 440     </listitem>
 441     <listitem>
 442      <para>
 443       FreeBSD: <ulink url="http://www.freshports.org/net/yaz"/>
 444      </para>
 445     </listitem>
 446     <listitem>
 447      <para>
 448       Debian: <ulink url="http://packages.debian.org/search?keywords=yaz"/>
 449      </para>
 450     </listitem>
 451     <listitem>
 452      <para>
 453       Ubuntu: <ulink url="https://launchpad.net/ubuntu/+source/yaz"/>
 454      </para>
 455     </listitem>
 456     <listitem>
 457      <para>
 458       NetBSD:
 459       <ulink url="http://ftp.netbsd.org/pub/pkgsrc/current/pkgsrc/net/yaz/README.html"/>
 460      </para>
 461     </listitem>
 462    </itemizedlist>
 463    <sect2 id="installation.source.unix">
 464     <title>Compiling from source on Unix</title>
 465     <para>
 466      Note that if your system doesn't have a native ANSI C compiler, you may
 467      have to acquire one separately. We recommend
 468      <ulink url="&url.gcc;">GCC</ulink>.
 469     </para>
 470     <para>
 471      If you wish to use character set conversion facilities in &yaz; or if you
 472      are compiling &yaz; for use with Zebra it is a good idea to ensure that
 473      the iconv library is installed. Some Unixes today already have it
 474      - if not, we suggest
 475      <ulink url="&url.libiconv;">GNU libiconv</ulink>.
 476     </para>
 477     <para>
 478      YAZ 3.0.16 and later includes a wrapper for the
 479      <ulink url="&url.icu;">ICU</ulink>
 480      (International Components for Unicode).
 481      In order to use this, the developer version of the ICU library
 482      must be available. ICU support is recommended for applications
 483      such as Pazpar2 and Zebra.
 484     </para>
 485     <para>
 486      The <ulink url="&url.libxslt;">libxslt</ulink>,
 487      <ulink url="&url.libxml2;">libxml2</ulink> librararies are required
 488      if &yaz; is to support SRU/Solr.
 489      These libraries are very portable and should compile out-of-the
 490      box on virtually all Unix platforms. It is available in binary
 491      forms for Linux and others.
 492     </para>
 493     <para>
 494      The GNU tools
 495      <ulink url="&url.autoconf;">Autoconf</ulink>,
 496      <ulink url="&url.automake;">Automake</ulink> and
 497      <ulink url="&url.libtool;">Libtool</ulink>
 498      are used to generate Makefiles and configure &yaz; for the system.
 499      You do <emphasis>not</emphasis> these tools unless you're using the
 500      Git version of &yaz;.
 501     </para>
 502     <para>
 503      The CQL parser for &yaz; is built using
 504      GNU <ulink url="&url.bison;">Bison</ulink>.
 505      This tool is only needed if you're using the Git version of &yaz;.
 506     </para>
 507     <para>
 508      &yaz; includes a tiny ASN.1 compiler. This compiler is
 509      written in <ulink url="&url.tcl;">Tcl</ulink>.
 510      But as for Bison you do not need it unless you're using Git
 511      version of &yaz; or you're using the compiler to built own codecs
 512      for private ASN.1.
 513     </para>
 514     <para>
 515      Generally it should be sufficient to run configure without options,
 516      like this:
 517     </para>
 518     <screen>
 519      ./configure
 520     </screen>
 521     <para>
 522      The configure script attempts to use use the C compiler specified by
 523      the <literal>CC</literal> environment variable. If not set, GNU C will be
 524      used if it is available. The <literal>CFLAGS</literal> environment
 525      variable holds options to be passed to the C compiler. If you're using
 526      Bourne-compatible shell you may pass something like this to use a
 527      particular C compiler with optimization enabled:
 528     </para>
 529     <screen>
 530      CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
 531     </screen>
 532     <para>
 533      To customize &yaz;, the configure script also accepts a set of options.
 534      The most important are:
 535      <variablelist>
 536       <varlistentry>
 537        <term>
 538         <literal>--prefix</literal>=<replaceable>prefix</replaceable>
 539        </term>
 540        <listitem>
 541         <para>Specifies installation prefix for &yaz;. This is
 542         only needed if you run <literal>make install</literal> later to
 543         perform a "system" installation. The prefix is
 544         <literal>/usr/local</literal> if not specified.
 545         </para>
 546        </listitem>
 547       </varlistentry>
 548       <varlistentry>
 549        <term>
 550         <literal>--enable-tcpd</literal>
 551        </term>
 552        <listitem>
 553         <para>The front end server will be built using Wietse's
 554         <ulink url="&url.tcpwrapper;">TCP wrapper library</ulink>.
 555         It allows you to allow/deny clients depending on IP number.
 556         The TCP wrapper library is often used in GNU/Linux and
 557         BSD distributions.
 558         See
 559         <citerefentry>
 560          <refentrytitle>hosts_access</refentrytitle>
 561          <manvolnum>5</manvolnum>
 562         </citerefentry>
 563         and
 564         <citerefentry>
 565          <refentrytitle>tcpd</refentrytitle>
 566          <manvolnum>8</manvolnum>
 567          </citerefentry>.
 568         </para>
 569        </listitem>
 570       </varlistentry>
 571       <varlistentry>
 572        <term>
 573         <literal>--enable-threads</literal>
 574        </term>
 575        <listitem>
 576         <para>&yaz; will be built using POSIX threads.
 577         Specifically, <constant>_REENTRANT</constant> will be defined during
 578         compilation.
 579         </para>
 580        </listitem>
 581       </varlistentry>
 582       <varlistentry>
 583        <term>
 584         <literal>--disable-shared</literal>
 585        </term>
 586        <listitem>
 587         <para>The make process will not create shared
 588         libraries (also known as shared objects <filename>.so</filename>).
 589         By default, shared libraries are created -
 590         equivalent to <literal>--enable-shared</literal>.
 591        </para>
 592        </listitem>
 593       </varlistentry>
 594       <varlistentry>
 595        <term>
 596         <literal>--disable-shared</literal>
 597        </term>
 598        <listitem>
 599         <para>The make process will not create
 600         static libraries (<filename>.a</filename>).
 601         By default, static libraries are created -
 602         equivalent to <literal>--enable-static</literal>.
 603         </para>
 604        </listitem>
 605       </varlistentry>
 606       <varlistentry>
 607        <term>
 608         <literal>--with-iconv</literal>[=<replaceable>prefix</replaceable>]
 609        </term>
 610        <listitem>
 611         <para>Compile &yaz; with iconv library in directory
 612         <replaceable>prefix</replaceable>. By default configure will
 613         search for iconv on the system. Use this option if it
 614         doesn't find iconv. Alternatively,
 615         <literal>--without-iconv</literal>, can be uset to force &yaz;
 616         not to use iconv.
 617         </para>
 618        </listitem>
 619       </varlistentry>
 620       <varlistentry>
 621        <term>
 622         <literal>--with-xslt</literal>[=<replaceable>prefix</replaceable>]
 623        </term>
 624        <listitem>
 625         <para>Compile &yaz; with
 626         <ulink url="&url.libxslt;">libxslt</ulink> in directory
 627         <replaceable>prefix</replaceable>.
 628         Use this option if you want XSLT and XML support.
 629         By default, configure will
 630         search for libxslt on the system. Use this option if it
 631         libxslt is not found automatically. Alternatively,
 632         <literal>--without-xslt</literal>, can be used to force &yaz;
 633         not to use libxslt.
 634         </para>
 635        </listitem>
 636       </varlistentry>
 637       <varlistentry>
 638        <term>
 639         <literal>--with-xml2</literal>[=<replaceable>prefix</replaceable>]
 640        </term>
 641        <listitem>
 642         <para>Compile &yaz; with
 643         <ulink url="&url.libxml2;">libxml2</ulink> in directory
 644         <replaceable>prefix</replaceable>.
 645         Use this option if you want &yaz; to use XML and support SRU/Solr.
 646         By default, configure will
 647         search for libxml2 on the system. Use this option if it
 648         libxml2 is not found automatically. Alternatively,
 649         <literal>--without-xml2</literal>, can be used to force &yaz;
 650         not to use libxml2.
 651         </para>
 652         <para>
 653          Note that option <literal>--with-xslt</literal>
 654          also enables libxml2.
 655         </para>
 656        </listitem>
 657       </varlistentry>
 658       <varlistentry>
 659        <term>
 660         <literal>--with-gnutls</literal>[=<replaceable>prefix</replaceable>]
 661        </term>
 662        <listitem>
 663         <para>&yaz; will be linked with the GNU TLS libraries and
 664         an SSL COMSTACK will be provided. By default configure enables
 665         SSL support for YAZ if the GNU TLS development libraries are found
 666         on the system.
 667         </para>
 668        </listitem>
 669       </varlistentry>
 670       <varlistentry>
 671        <term>
 672         <literal>--with-icu</literal>[=<replaceable>prefix</replaceable>]
 673        </term>
 674        <listitem>
 675         <para>&yaz; will be linked the
 676         <ulink url="&url.icu;">ICU</ulink> library in the prefix if given.
 677         If prefix is not given, the libraries exposed by the script
 678         <application>icu-config</application> will be used if found.
 679         </para>
 680        </listitem>
 681       </varlistentry>
 682
 683       <varlistentry>
 684        <term>
 685         <literal>--with-libgcrypt</literal>[=<replaceable>prefix</replaceable>]
 686        </term>
 687        <listitem>
 688         <para>&yaz; will be linked with
 689         <ulink url="&url.libgcrypt;">Libgcrypt</ulink> in the prefix if given.
 690         If prefix is not given, the libraries exposed by the script
 691         <application>libgcrypt-config</application> will be used if found.
 692         </para>
 693        </listitem>
 694       </varlistentry>
 695       <varlistentry>
 696        <term>
 697         <literal>--with-memcached</literal>
 698        </term>
 699        <listitem>
 700         <para>&yaz; will be linked with
 701         <ulink url="&url.libmemcached;">libMemcached</ulink> to allow
 702         for result-set caching for ZOOM.
 703         The prefix can not be given. Note that YAZ will only search
 704         for libMemcached if Libgcrypt is also enabled.
 705        </para>
 706        </listitem>
 707       </varlistentry>
 708      </variablelist>
 709     </para>
 710     <para>
 711      When configured, build the software by typing:
 712      <screen>
 713       make
 714      </screen>
 715     </para>
 716     <para>
 717      The following files are generated by the make process:
 718      <variablelist>
 719       <varlistentry>
 720        <term><filename>src/libyaz.la</filename></term>
 721        <listitem><para>
 722         Main &yaz; library. This is no ordinary library. It's
 723         a Libtool archive.
 724         By default, &yaz; creates a static library in
 725         <filename>lib/.libs/libyaz.a</filename>.
 726        </para></listitem>
 727       </varlistentry>
 728       <varlistentry>
 729        <term><filename>src/libyaz_server.la</filename></term>
 730        <listitem><para>
 731          Generic Frontend server. This is an add-on for libyaz.la.
 732          Code in this library uses POSIX threads functions - if POSIX
 733          threads are available on the platform.
 734         </para></listitem>
 735       </varlistentry>
 736       <varlistentry>
 737        <term><filename>src/libyaz_icu.la</filename></term>
 738        <listitem><para>
 739         Functions that wrap the ICU library.
 740         </para></listitem>
 741       </varlistentry>
 742       <varlistentry>
 743        <term><filename>ztest/yaz-ztest</filename></term>
 744        <listitem><para>Test Z39.50 server.
 745        </para></listitem>
 746       </varlistentry>
 747       <varlistentry>
 748        <term><filename>client/yaz-client</filename></term>
 749        <listitem><para>Z39.50 client for testing the protocol.
 750        See chapter <link linkend="yaz-client">
 751        YAZ client</link> for more information.
 752        </para></listitem>
 753       </varlistentry>
 754       <varlistentry>
 755        <term><filename>util/yaz-config</filename></term>
 756        <listitem><para>A Bourne-shell script, generated by configure, that
 757        specifies how external applications should compile - and link with
 758        &yaz;.
 759        </para></listitem>
 760       </varlistentry>
 761       <varlistentry>
 762        <term><filename>util/yaz-asncomp</filename></term>
 763        <listitem><para>The ASN.1 compiler for &yaz;. Requires the
 764        Tcl Shell, <application>tclsh</application>, in
 765        <literal>PATH</literal> to operate.
 766        </para></listitem>
 767       </varlistentry>
 768       <varlistentry>
 769        <term><filename>util/yaz-iconv</filename></term>
 770        <listitem><para>This program converts data in one character set to
 771        another. This command exercises the YAZ character set
 772        conversion API.
 773        </para></listitem>
 774       </varlistentry>
 775       <varlistentry>
 776        <term><filename>util/yaz-marcdump</filename></term>
 777        <listitem><para>This program parses ISO2709 encoded MARC records
 778        and prints them in line-format or XML.
 779        </para></listitem>
 780       </varlistentry>
 781       <varlistentry>
 782        <term><filename>util/yaz-icu</filename></term>
 783        <listitem><para>This program exposes the ICU wrapper library if that
 784        is enabled for YAZ. Only if ICU is available this program is
 785        useful.
 786        </para></listitem>
 787       </varlistentry>
 788       <varlistentry>
 789        <term><filename>util/yaz-url</filename></term>
 790        <listitem><para>This program is a simple HTTP page fetcher ala
 791        wget or curl.
 792        </para></listitem>
 793       </varlistentry>
 794       <varlistentry>
 795        <term><filename>zoom/zoomsh</filename></term>
 796        <listitem><para>
 797         A simple shell implemented on top of the
 798         <link linkend="zoom">ZOOM</link> functions.
 799         The shell is a command line application that allows you to enter
 800         simple commands to perform ZOOM operations.
 801        </para></listitem>
 802       </varlistentry>
 803       <varlistentry>
 804        <term><filename>zoom/zoomtst1</filename>,
 805        <filename>zoom/zoomtst2</filename>, ..</term>
 806        <listitem><para>
 807         Several small applications that demonstrates the ZOOM API.
 808        </para></listitem>
 809       </varlistentry>
 810      </variablelist>
 811     </para>
 812     <para>
 813      If you wish to install &yaz; in system directories
 814      <filename>/usr/local/bin</filename>,
 815      <filename>/usr/local/lib</filename> .. etc, you can type:
 816     </para>
 817     <screen>
 818      make install
 819     </screen>
 820     <para>
 821      You probably need to have root access in order to perform this.
 822      You must specify the <literal>--prefix</literal> option for configure if
 823      you wish to install &yaz; in other directories than the default
 824      <filename>/usr/local/</filename>.
 825     </para>
 826     <para>
 827      If you wish to perform an un-installation of &yaz;, use:
 828     </para>
 829     <screen>
 830      make uninstall
 831     </screen>
 832     <para>
 833      This will only work if you haven't reconfigured &yaz; (and therefore
 834      changed installation prefix). Note that uninstall will not
 835      remove directories created by make install, e.g.
 836      <filename>/usr/local/include/yaz</filename>.
 837     </para>
 838    </sect2>
 839    <sect2 id="installation-linking-yaz-unix">
 840     <title>How to make apps using YAZ on UNIX</title>
 841     <para>
 842      This section describes how to compile - and link your own
 843      applications using the &yaz; toolkit.
 844      If you're used to Makefiles this shouldn't be hard. As for
 845      other libraries you have used before, you have to set a proper include
 846      path for your C/C++ compiler and specify the location of
 847      &yaz; libraries. You can do it by hand, but generally we suggest
 848      you use the <filename>yaz-config</filename> that is generated
 849      by <filename>configure</filename>. This is especially
 850      important if you're using the threaded version of &yaz; which
 851      require you to pass more options to your linker/compiler.
 852     </para>
 853     <para>
 854      The <filename>yaz-config</filename> script accepts command line
 855      options that makes the <filename>yaz-config</filename> script print
 856      options that you should use in your make process.
 857      The most important ones are:
 858      <literal>--cflags</literal>, <literal>--libs</literal>
 859      which prints C compiler flags, and linker flags respectively.
 860     </para>
 861     <para>
 862      A small and complete <literal>Makefile</literal> for a C
 863      application consisting of one source file,
 864      <filename>myprog.c</filename>, may look like this:
 865      <screen>
 866       YAZCONFIG=/usr/local/bin/yaz-config
 867       CFLAGS=`$(YAZCONFIG) --cflags`
 868       LIBS=`$(YAZCONFIG) --libs`
 869       myprog: myprog.o
 870          $(CC) $(CFLAGS) -o myprog myprog.o $(LIBS)
 871       </screen>
 872     </para>
 873     <para>
 874      The CFLAGS variable consists of a C compiler directive that will set
 875      the include path to the <emphasis>parent</emphasis> directory
 876      of <filename>yaz</filename>. That is, if &yaz; header files were
 877      installed in <filename>/usr/local/include/yaz</filename>,
 878      then include path is set to <filename>/usr/local/include</filename>.
 879      Therefore, in your applications you should use
 880      <screen>
 881       #include &lt;yaz/proto.h>
 882      </screen>
 883      and <emphasis>not</emphasis>
 884      <screen>
 885       #include &lt;proto.h>
 886      </screen>
 887     </para>
 888     <para>
 889      For Libtool users, the <filename>yaz-config</filename> script provides
 890      a different variant of option <literal>--libs</literal>, called
 891      <literal>--lalibs</literal> that returns the name of the
 892      Libtool archive(s) for &yaz; rather than the ordinary ones.
 893     </para>
 894     <para>
 895      For applications using the threaded version of &yaz;,
 896      specify <literal>threads</literal> after the
 897      other options. When <literal>threads</literal> is given,
 898      more flags and linker flags will be printed by
 899      <filename>yaz-config</filename>. If our previous example was
 900       using threads, you'd have to modify the lines that set
 901      <literal>CFLAGS</literal> and <literal>LIBS</literal> as
 902      follows:
 903      <screen>
 904       CFLAGS=`$(YAZCONFIG) --cflags threads`
 905       LIBS=`$(YAZCONFIG) --libs threads`
 906      </screen>
 907      There is no need specify POSIX thread libraries in your Makefile.
 908      The <literal>LIBS</literal> variable includes that as well.
 909     </para>
 910    </sect2>
 911   </sect1>
 912   <sect1 id="installation.win32">
 913    <title>WIN32</title>
 914    <para>The easiest way to install YAZ on Windows is by downloading
 915    an installer from
 916    <ulink url="&url.yaz.download.win32;">here</ulink>.
 917    The installer comes with source too - in case you wish to
 918    compile YAZ with different compiler options, etc.
 919    </para>
 920
 921    <sect2 id="installation.win32.source">
 922     <title>Compiling from Source on WIN32</title>
 923     <para>
 924      &yaz; is shipped with "makefiles" for the NMAKE tool that comes
 925      with <ulink url="&url.vstudio;">
 926      Microsoft Visual Studio</ulink>. It has been tested with
 927      Microsoft Visual Studio 2003/2005/2008.
 928     </para>
 929     <para>
 930      Start a command prompt and switch the sub directory
 931      <filename>WIN</filename> where the file <filename>makefile</filename>
 932      is located. Customize the installation by editing the
 933      <filename>makefile</filename> file (for example by using notepad).
 934      The following summarizes the most important settings in that file:
 935      <variablelist>
 936       <varlistentry>
 937        <term><literal>DEBUG</literal></term>
 938        <listitem><para>
 939         If set to 1, the software is
 940         compiled with debugging libraries (code generation is
 941         multi-threaded debug DLL).
 942         If set to 0, the software is compiled with release libraries
 943         (code generation is multi-threaded DLL).
 944        </para></listitem>
 945       </varlistentry>
 946       <varlistentry>
 947        <term><literal>HAVE_TCL</literal>, <literal>TCL</literal></term>
 948        <listitem><para>
 949         If <literal>HAVE_TCL</literal> is set to 1, nmake will
 950         use the ASN.1 compiler (<ulink url="&url.tcl;">Tcl</ulink> based).
 951         You must set <literal>TCL</literal> to the full path of the Tcl
 952         interpreter. A Windows version of Tcl is part of
 953         <ulink url="&url.gitwindows;">Git for Windows</ulink>.
 954        </para>
 955        <para>
 956         If you do not have Tcl installed, set
 957         <literal>HAVE_TCL</literal> to 0.
 958        </para></listitem>
 959       </varlistentry>
 960       <varlistentry>
 961        <term><literal>HAVE_BISON</literal>,
 962        <literal>BISON</literal></term>
 963        <listitem><para>
 964         If GNU Bison is present, you might set <literal>HAVE_BISON</literal>
 965         to 1 and specify the Bison executable in <literal>BISON</literal>.
 966         Bison is only required if you use the Git version of
 967         YAZ or if you modify the grammar for CQL
 968         (<filename>cql.y</filename>).
 969        </para>
 970        <para>
 971         A Windows version of GNU Bison is part of
 972         <ulink url="&url.gitwindows;">Git for Windows</ulink>.
 973        </para></listitem>
 974       </varlistentry>
 975       <varlistentry>
 976        <term><literal>HAVE_ICONV</literal>,
 977        <literal>ICONV_DIR</literal></term>
 978        <listitem><para>
 979         If <literal>HAVE_ICONV</literal> is set to 1, YAZ is compiled
 980         with iconv support. In this configuration, set
 981         <literal>ICONV_DIR</literal> to the iconv source directory.
 982        </para></listitem>
 983       </varlistentry>
 984       <varlistentry>
 985        <term><literal>HAVE_LIBXML2</literal>,
 986        <literal>LIBXML2_DIR</literal></term>
 987        <listitem>
 988         <para>
 989          If <literal>HAVE_LIBXML2</literal> is set to 1, YAZ is compiled
 990          with SRU support. In this configuration, set
 991          <literal>LIBXML2_DIR</literal> to the
 992          <ulink url="&url.libxml2;">libxml2</ulink> source directory
 993          and
 994          <literal>ZLIB_DIR</literal> to the zlib directory.
 995         </para>
 996         <para>
 997          Windows versions of libxslt, libxml2, zlib and iconv can be found
 998          <ulink url="&url.libxml2.download.win32;">
 999           Igor Zlatkovi&#x0107;' site</ulink>.
1000         </para>
1001         <note>
1002          <para>
1003           YAZ is not using zlib but libxml2 is depending on it.
1004          </para>
1005         </note>
1006        </listitem>
1007       </varlistentry>
1008       <varlistentry>
1009        <term><literal>HAVE_LIBXSLT</literal>,
1010        <literal>LIBXSLT_DIR</literal></term>
1011        <listitem>
1012         <para>
1013          If <literal>HAVE_LIBXSLT</literal> is set to 1, YAZ is compiled
1014          with XSLT support. In this configuration, set
1015          <literal>LIBXSLT_DIR</literal> to the
1016          <ulink url="&url.libxslt;">libxslt</ulink> source directory.
1017         </para>
1018         <note>
1019          <para>
1020           libxslt depends libxml2.
1021          </para>
1022         </note>
1023        </listitem>
1024       </varlistentry>
1025       <varlistentry>
1026        <term><literal>HAVE_ICU</literal>,
1027        <literal>ICU_DIR</literal></term>
1028        <listitem>
1029         <para>
1030          If <literal>HAVE_ICU</literal> is set to 1, YAZ is compiled
1031          with <ulink url="&url.icu;">ICU</ulink> support.
1032          In this configuration, set
1033          <literal>ICU_DIR</literal> to the
1034          <ulink url="&url.icu;">ICU</ulink> source directory.
1035         </para>
1036        </listitem>
1037       </varlistentry>
1038      </variablelist>
1039     </para>
1040     <para>
1041      When satisfied with the settings in the makefile, type
1042      <screen>
1043       nmake
1044      </screen>
1045     </para>
1046     <note>
1047      <para>
1048       If the <filename>nmake</filename> command is not found on your system
1049       you probably haven't defined the environment variables required to
1050       use that tool. To fix that, find and run the batch file
1051       <filename>vcvars32.bat</filename>. You need to run it from within
1052       the command prompt or set the environment variables "globally";
1053       otherwise it doesn't work.
1054      </para>
1055     </note>
1056     <para>
1057      If you wish to recompile &yaz; - for example if you modify
1058      settings in the <filename>makefile</filename> you can delete
1059      object files, etc by running.
1060      <screen>
1061       nmake clean
1062      </screen>
1063     </para>
1064     <para>
1065      The following files are generated upon successful compilation:
1066      <variablelist>
1067       <varlistentry>
1068        <term><filename>bin/yaz&soversion;.dll</filename> /
1069        <filename>bin/yaz&soversion;d.dll</filename></term>
1070        <listitem><para>
1071         &yaz; Release/Debug DLL.
1072        </para></listitem>
1073       </varlistentry>
1074       <varlistentry>
1075        <term><filename>lib/yaz&soversion;.lib</filename> /
1076        <filename>lib/yaz&soversion;d.lib</filename></term>
1077        <listitem><para>
1078         Import library for <filename>yaz&soversion;.dll</filename> /
1079         <filename>yaz&soversion;d.dll</filename>.
1080       </para></listitem>
1081       </varlistentry>
1082       <varlistentry>
1083        <term><filename>bin/yaz_cond&soversion;.dll</filename> /
1084        <filename>bin/yaz_cond&soversion;d.dll</filename></term>
1085        <listitem><para>
1086         Release/Debug DLL for condition variable utilities (condvar.c).
1087        </para></listitem>
1088       </varlistentry>
1089       <varlistentry>
1090        <term><filename>lib/yaz_cond&soversion;.lib</filename> /
1091        <filename>lib/yaz_cond&soversion;d.lib</filename></term>
1092        <listitem><para>
1093         Import library for <filename>yaz_cond&soversion;.dll</filename> /
1094         <filename>yaz_cond&soversion;d.dll</filename>.
1095        </para></listitem>
1096       </varlistentry>
1097       <varlistentry>
1098        <term><filename>bin/yaz_icu&soversion;.dll</filename> /
1099        <filename>bin/yaz_icu&soversion;d.dll</filename></term>
1100        <listitem><para>
1101         Release/Debug DLL for the ICU wrapper utility.
1102         Only build if HAVE_ICU is 1.
1103        </para></listitem>
1104       </varlistentry>
1105       <varlistentry>
1106        <term><filename>lib/yaz_icu&soversion;.lib</filename> /
1107        <filename>lib/yaz_icu&soversion;d.lib</filename></term>
1108        <listitem><para>
1109         Import library for <filename>yaz_icu&soversion;.dll</filename> /
1110         <filename>yaz_icu&soversion;d.dll</filename>.
1111        </para></listitem>
1112       </varlistentry>
1113       <varlistentry>
1114        <term><filename>bin/yaz-ztest.exe</filename></term>
1115        <listitem><para>
1116         Z39.50 multi-threaded test/example server. It's a WIN32
1117         console application.
1118       </para></listitem>
1119       </varlistentry>
1120       <varlistentry>
1121        <term><filename>bin/yaz-client.exe</filename></term>
1122        <listitem><para>
1123         &yaz; Z39.50 client application. It's a WIN32 console application.
1124         See chapter <link linkend="yaz-client">YAZ client</link> for more
1125         information.
1126       </para></listitem>
1127       </varlistentry>
1128       <varlistentry>
1129        <term><filename>bin/yaz-icu.exe</filename></term>
1130        <listitem><para>This program exposes the ICU wrapper library if that
1131        is enabled for YAZ. Only if ICU is available this program is
1132        build.
1133       </para></listitem>
1134       </varlistentry>
1135       <varlistentry>
1136        <term><filename>bin/zoomsh.exe</filename></term>
1137        <listitem><para>
1138         Simple console application implemented on top of the
1139         <link linkend="zoom">ZOOM</link> functions.
1140         The application is a command line shell that allows you to enter
1141         simple commands to perform ZOOM operations.
1142       </para></listitem>
1143       </varlistentry>
1144       <varlistentry>
1145        <term><filename>bin/zoomtst1.exe</filename>,
1146        <filename>bin/zoomtst2.exe</filename>, ..</term>
1147        <listitem><para>
1148         Several small applications that demonstrates the ZOOM API.
1149       </para></listitem>
1150       </varlistentry>
1151      </variablelist>
1152     </para>
1153    </sect2>
1154
1155    <sect2 id="installation-linking-yaz-win32">
1156     <title>How to make apps using YAZ on WIN32</title>
1157     <para>
1158      This section will go though the process of linking your WIN32
1159      applications with &yaz;.
1160     </para>
1161     <para>
1162      Some people are confused by the fact that we use the nmake
1163      tool to build &yaz;. They think they have to do that too - in order
1164      to make their WIN32 applications work with &yaz;. The good news is that
1165      you don't have to. You can use the integrated environment of
1166      Visual Studio if desired for your own application.
1167     </para>
1168     <para>
1169      When setting up a project or Makefile you have to set the following:
1170      <variablelist>
1171       <varlistentry>
1172        <term>include path</term>
1173        <listitem><para>
1174         Set it to the <filename>include</filename> directory of &yaz;.
1175         </para></listitem>
1176       </varlistentry>
1177       <varlistentry>
1178        <term>import library <filename>yaz&soversion;.lib</filename></term>
1179        <listitem><para>
1180         You must link with this library. It's located in the
1181         sub directory <filename>lib</filename> of &yaz;.
1182         If you want to link with the debug version of &yaz;, you must
1183         link against <filename>yaz&soversion;d.lib</filename> instead.
1184        </para></listitem>
1185       </varlistentry>
1186       <varlistentry>
1187        <term>dynamic link library
1188        <filename>yaz&soversion;.dll</filename>
1189        </term>
1190        <listitem><para>
1191         This DLL must be in your execution path when you invoke
1192         your application. Specifically, you should distribute this
1193         DLL with your application.
1194        </para></listitem>
1195       </varlistentry>
1196      </variablelist>
1197     </para>
1198    </sect2>
1199   </sect1>
1200  </chapter>
1201  <!--
1202      ### Still to document:
1203      ZOOM_connection_errcode(c)
1204      ZOOM_connection_errmsg(c)
1205      ZOOM_connection_addinfo(c)
1206      ZOOM_connection_addinfo(c)
1207      ZOOM_connection_diagset(c);
1208      ZOOM_connection_save_apdu_wrbuf
1209      ZOOM_diag_str(error)
1210      ZOOM_resultset_record_immediate(s, pos)
1211      ZOOM_resultset_cache_reset(r)
1212      ZOOM_options_set_callback(opt, function, handle)
1213      ZOOM_options_create_with_parent2(parent1, parent2)
1214      ZOOM_options_getl(opt, name, len)
1215      ZOOM_options_setl(opt, name, value, len)
1216      ZOOM_options_get_bool(opt, name, defa)
1217      ZOOM_options_get_int(opt, name, defa)
1218      ZOOM_options_set_int(opt, name, value)
1219  -->
1220  <chapter id="zoom">
1221   <title>ZOOM</title>
1222   <para>
1223    &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is
1224    an initiative started by Mike Taylor (Mike is from the UK, which
1225    explains the peculiar name of the model). The goal of &zoom; is to
1226    provide a common Z39.50 client API not bound to a particular
1227    programming language or toolkit.
1228   </para>
1229   <para>
1230    From YAZ version 2.1.12, <ulink url="&url.sru;">SRU</ulink> is supported.
1231    You can make SRU ZOOM connections by specifying scheme
1232    <literal>http://</literal> for the hostname for a connection.
1233    The dialect of SRU used is specified by the value of the
1234    connection's <literal>sru</literal> option, which may be SRU over
1235    HTTP GET (<literal>get</literal>),
1236    SRU over HTTP POST (<literal>post</literal>), (SRU over
1237    SOAP) (<literal>soap</literal>) or <literal>solr</literal>
1238    (<ulink url="&url.solr;">Solr</ulink> Web Service).
1239    Using the facility for embedding options in target strings, a
1240    connection can be forced to use SRU rather the SRW (the default) by
1241    prefixing the target string with <literal>sru=get,</literal>, like this:
1242    <literal>sru=get,http://sru.miketaylor.org.uk:80/sru.pl</literal>
1243   </para>
1244   <para>
1245    <ulink url="&url.solr;">Solr</ulink>  protocol support was added to
1246    YAZ in version 4.1.0, as a dialect of a SRU protocol, since both are
1247    HTTP based protocols.
1248   </para>
1249   <para>
1250    The lack of a simple Z39.50 client API for &yaz; has become more
1251    and more apparent over time. So when the first &zoom; specification
1252    became available,
1253    an implementation for &yaz; was quickly developed. For the first time, it is
1254    now as easy (or easier!) to develop clients than servers with &yaz;. This
1255    chapter describes the &zoom; C binding. Before going further, please
1256    reconsider whether C is the right programming language for the job.
1257    There are other language bindings available for &yaz;, and still
1258    more
1259    are in active development. See the
1260    <ulink url="&url.zoom;">ZOOM web-site</ulink> for
1261    more information.
1262   </para>
1263   <para>
1264    In order to fully understand this chapter you should read and
1265    try the example programs <literal>zoomtst1.c</literal>,
1266    <literal>zoomtst2.c</literal>, .. in the <literal>zoom</literal>
1267    directory.
1268   </para>
1269   <para>
1270    The C language misses features found in object oriented languages
1271    such as C++, Java, etc. For example, you'll have to manually,
1272    destroy all objects you create, even though you may think of them as
1273    temporary. Most objects has a <literal>_create</literal> - and a
1274    <literal>_destroy</literal> variant.
1275    All objects are in fact pointers to internal stuff, but you don't see
1276    that because of typedefs. All destroy methods should gracefully ignore a
1277    <literal>NULL</literal> pointer.
1278   </para>
1279   <para>
1280    In each of the sections below you'll find a sub section called
1281    protocol behavior, that describes how the API maps to the Z39.50
1282    protocol.
1283   </para>
1284   <sect1 id="zoom-connections">
1285    <title>Connections</title>
1286    <para>The Connection object is a session with a target.
1287    </para>
1288    <synopsis>
1289     #include &lt;yaz/zoom.h>
1290
1291     ZOOM_connection ZOOM_connection_new(const char *host, int portnum);
1292
1293     ZOOM_connection ZOOM_connection_create(ZOOM_options options);
1294
1295     void ZOOM_connection_connect(ZOOM_connection c, const char *host,
1296                                  int portnum);
1297     void ZOOM_connection_destroy(ZOOM_connection c);
1298    </synopsis>
1299    <para>
1300     Connection objects are created with either function
1301     <function>ZOOM_connection_new</function> or
1302     <function>ZOOM_connection_create</function>.
1303     The former creates and automatically attempts to establish a network
1304     connection with the target. The latter doesn't establish
1305     a connection immediately, thus allowing you to specify options
1306     before establishing network connection using the function
1307     <function>ZOOM_connection_connect</function>.
1308     If the port number, <literal>portnum</literal>, is zero, the
1309     <literal>host</literal> is consulted for a port specification.
1310     If no port is given, 210 is used. A colon denotes the beginning of
1311     a port number in the host string. If the host string includes a
1312     slash, the following part specifies a database for the connection.
1313    </para>
1314    <para>
1315     You can prefix the host with a scheme followed by colon. The
1316     default scheme is <literal>tcp</literal> (Z39.50 protocol).
1317     The scheme <literal>http</literal> selects SRU/get over HTTP by default,
1318     but can overridded to use SRU/post, SRW and the Solr protocol.
1319    </para>
1320    <para>
1321     You can prefix the scheme-qualified host-string with one or more
1322     comma-separated
1323     <literal><parameter>key</parameter>=<parameter>value</parameter></literal>
1324     sequences, each of which represents an option to be set into the
1325     connection structure <emphasis>before</emphasis> the
1326     protocol-level connection is forged and the initialization
1327     handshake takes place.  This facility can be used to provide
1328     authentication credentials, as in host-strings such as:
1329     <literal>user=admin,password=halfAm4n,tcp:localhost:8017/db</literal>
1330    </para>
1331    <para>
1332     Connection objects should be destroyed using the function
1333     <function>ZOOM_connection_destroy</function>.
1334    </para>
1335    <synopsis>
1336     void ZOOM_connection_option_set(ZOOM_connection c,
1337                                     const char *key, const char *val);
1338
1339     void ZOOM_connection_option_setl(ZOOM_connection c,
1340                                      const char *key,
1341                                      const char *val, int len);
1342
1343     const char *ZOOM_connection_option_get(ZOOM_connection c,
1344                                            const char *key);
1345     const char *ZOOM_connection_option_getl(ZOOM_connection c,
1346                                             const char *key,
1347                                             int *lenp);
1348    </synopsis>
1349    <para>
1350     The functions <function>ZOOM_connection_option_set</function> and
1351     <function>ZOOM_connection_option_setl</function> allows you to
1352     set an option given by <parameter>key</parameter> to the value
1353     <parameter>value</parameter> for the connection.
1354     For <function>ZOOM_connection_option_set</function>, the
1355     value is assumed to be a 0-terminated string. Function
1356     <function>ZOOM_connection_option_setl</function> specifies a
1357     value of a certain size (len).
1358    </para>
1359    <para>
1360     Functions <function>ZOOM_connection_option_get</function> and
1361     <function>ZOOM_connection_option_getl</function> returns
1362     the value for an option given by <parameter>key</parameter>.
1363    </para>
1364    <table id="zoom-connection-options" frame="top">
1365     <title>ZOOM Connection Options</title>
1366     <tgroup cols="3">
1367      <colspec colwidth="4*" colname="name"></colspec>
1368      <colspec colwidth="7*" colname="description"></colspec>
1369      <colspec colwidth="3*" colname="default"></colspec>
1370      <thead>
1371       <row>
1372        <entry>Option</entry>
1373        <entry>Description</entry>
1374        <entry>Default</entry>
1375       </row>
1376      </thead>
1377      <tbody>
1378       <row><entry>
1379        implementationName</entry><entry>Name of Your client
1380       </entry><entry>none</entry></row>
1381       <row><entry>
1382        user</entry><entry>Authentication user name
1383       </entry><entry>none</entry></row>
1384       <row><entry>
1385        group</entry><entry>Authentication group name
1386       </entry><entry>none</entry></row>
1387       <row><entry>
1388        password</entry><entry>Authentication password.
1389       </entry><entry>none</entry></row>
1390       <row><entry>
1391        authenticationMode</entry><entry>How authentication is encoded.
1392       </entry><entry>basic</entry></row>
1393       <row><entry>
1394        host</entry><entry>Target host. This setting is "read-only".
1395        It's automatically set internally when connecting to a target.
1396       </entry><entry>none</entry></row>
1397       <row><entry>
1398        proxy</entry><entry>Proxy host. If set, the logical host
1399        is encoded in the otherInfo area of the Z39.50 Init PDU
1400        with OID 1.2.840.10003.10.1000.81.1.
1401       </entry><entry>none</entry></row>
1402       <row><entry>
1403        clientIP</entry><entry>Client IP. If set, is
1404        encoded in the otherInfo area of a Z39.50 PDU with OID
1405        1.2.840.10003.10.1000.81.3. Holds the original IP addreses
1406        of a client. Is used of ZOOM is used in a gateway of some sort.
1407       </entry><entry>none</entry></row>
1408       <row><entry>
1409        async</entry><entry>If true (1) the connection operates in
1410        asynchronous operation which means that all calls are non-blocking
1411        except
1412        <link linkend="zoom.events"><function>ZOOM_event</function></link>.
1413       </entry><entry>0</entry></row>
1414       <row><entry>
1415        maximumRecordSize</entry><entry> Maximum size of single record.
1416       </entry><entry>1 MB</entry></row>
1417       <row><entry>
1418        preferredMessageSize</entry><entry> Maximum size of multiple records.
1419       </entry><entry>1 MB</entry></row>
1420       <row><entry>
1421        lang</entry><entry> Language for negotiation.
1422       </entry><entry>none</entry></row>
1423       <row><entry>
1424        charset</entry><entry> Character set for negotiation.
1425       </entry><entry>none</entry></row>
1426       <row><entry>
1427        serverImplementationId</entry><entry>
1428        Implementation ID of server.  (The old targetImplementationId
1429        option is also supported for the benefit of old applications.)
1430       </entry><entry>none</entry></row>
1431       <row><entry>
1432        targetImplementationName</entry><entry>
1433        Implementation Name of server.  (The old
1434        targetImplementationName option is also supported for the
1435        benefit of old applications.)
1436       </entry><entry>none</entry></row>
1437       <row><entry>
1438        serverImplementationVersion</entry><entry>
1439        Implementation Version of server.  (the old
1440        targetImplementationVersion option is also supported for the
1441        benefit of old applications.)
1442       </entry><entry>none</entry></row>
1443       <row><entry>
1444        databaseName</entry><entry>One or more database names
1445        separated by character plus (<literal>+</literal>), which to
1446        be used by subsequent search requests on this Connection.
1447       </entry><entry>Default</entry></row>
1448       <row><entry>
1449        piggyback</entry><entry>True (1) if piggyback should be
1450        used in searches; false (0) if not.
1451       </entry><entry>1</entry></row>
1452       <row><entry>
1453        smallSetUpperBound</entry><entry>If hits is less than or equal to this
1454        value, then target will return all records using small element set name
1455       </entry><entry>0</entry></row>
1456       <row><entry>
1457        largeSetLowerBound</entry><entry>If hits is greater than this
1458        value, the target will return no records.
1459       </entry><entry>1</entry></row>
1460       <row><entry>
1461        mediumSetPresentNumber</entry><entry>This value represents
1462        the number of records to be returned as part of a search when when
1463        hits is less than or equal to large set lower bound and if hits
1464        is greater than small set upper bound.
1465       </entry><entry>0</entry></row>
1466       <row><entry>
1467        smallSetElementSetName</entry><entry>
1468        The element set name to be used for small result sets.
1469       </entry><entry>none</entry></row>
1470       <row><entry>
1471        mediumSetElementSetName</entry><entry>
1472        The element set name to be for medium-sized result sets.
1473       </entry><entry>none</entry></row>
1474       <row><entry>
1475        init_opt_search, init_opt_present, init_opt_delSet, etc.</entry><entry>
1476        After a successful Init, these options may be interrogated to
1477        discover whether the server claims to support the specified
1478        operations.
1479       </entry><entry>none</entry></row>
1480       <row>
1481        <entry>sru</entry><entry>
1482        SRU/Solr transport type. Must be either <literal>soap</literal>,
1483        <literal>get</literal>, <literal>post</literal>, or
1484        <literal>solr</literal>.
1485       </entry><entry>soap</entry></row>
1486       <row><entry>
1487        sru_version</entry><entry>
1488        SRU/SRW version. Should be <literal>1.1</literal>, or
1489        <literal>1.2</literal>. This is , prior to connect, the version
1490        to offer (highest version). And following connect (in fact
1491        first operation), holds the negotiated version with the server
1492        (same or lower version).
1493       </entry><entry>1.2</entry></row>
1494       <row id="zoom.facets.option"><entry>
1495        facets</entry><entry>
1496        Requested or recommend facets may be given before a search is sent.
1497        The value of this setting is described in <xref linkend="facets"/>
1498        For inspection of the facets returned, refer to the functions
1499        described in <xref linkend="zoom.facets"/>.
1500       </entry><entry>none</entry></row>
1501       <row><entry>
1502        apdulog</entry><entry>
1503        If set to a true value such as "1", a log of low-level
1504        protocol packets is emitted on standard error stream.  This
1505        can be very useful for debugging.
1506       </entry><entry>0</entry></row>
1507       <row><entry>
1508        saveAPDU</entry><entry>
1509        If set to a true value such as "1", a log of low-level
1510        protocol packets is saved. The log can be retrieved by reading
1511        option APDU. Setting saveAPDU always has the side effect of
1512        resetting the currently saved log. This setting is
1513        <emphasis>write-only</emphasis>. If read, NULL will be returned.
1514        It is only recognized in
1515        <function>ZOOM_connection_option_set</function>.
1516       </entry><entry>0</entry></row>
1517       <row><entry>
1518        APDU</entry><entry>
1519        Returns the log of protocol packets. Will be empty if logging
1520        is not enabled (see saveAPDU above). This setting is
1521        <emphasis>read-only</emphasis>. It is only recognized if used
1522        in call to <function>ZOOM_connection_option_get</function> or
1523        <function>ZOOM_connection_option_getl</function>.
1524       </entry><entry></entry></row>
1525       <row><entry>
1526        memcached</entry><entry>
1527        If given and non-empty,
1528        <ulink url="&url.libmemcached;">libMemcached</ulink>
1529        will be configured for the connection.
1530        This option is inspected by ZOOM when a connection is  established.
1531        If the <literal>memcached</literal> option is given
1532        and YAZ is compiled without libMemcached support, an internal
1533        diagnostic (10018) will be thrown.
1534        libMemcached support is available for YAZ 5.0.13 or later. If this
1535        option is supplied for an earlier version of YAZ, it is
1536        <emphasis>ignored</emphasis>.
1537        The value of this option is a string passed verbatim to
1538        the <function>memcached</function> function part of libMemcached.
1539        Refer to man page
1540        <ulink url="http://manned.org/memcached.3">memcached(3)</ulink>.
1541        Earlier versions of libMemcached
1542        do not offer this function. In this case only the option
1543        <literal>--server=</literal><replaceable>host</replaceable> may
1544        be given (YAZ emulates that part of libMemcached).
1545       </entry><entry>none</entry></row>
1546      </tbody>
1547     </tgroup>
1548    </table>
1549    <para>
1550     If either option <literal>lang</literal> or <literal>charset</literal>
1551     is set, then
1552     <ulink url="&url.z39.50.charneg;">
1553      Character Set and Language Negotiation</ulink> is in effect.
1554    </para>
1555    <synopsis>
1556      int ZOOM_connection_error(ZOOM_connection c, const char **cp,
1557                                const char **addinfo);
1558      int ZOOM_connection_error_x(ZOOM_connection c, const char **cp,
1559                                  const char **addinfo, const char **dset);
1560    </synopsis>
1561    <para>
1562     Function <function>ZOOM_connection_error</function> checks for
1563     errors for the last operation(s) performed. The function returns
1564     zero if no errors occurred; non-zero otherwise indicating the error.
1565     Pointers <parameter>cp</parameter> and <parameter>addinfo</parameter>
1566     holds messages for the error and additional-info if passed as
1567     non-<literal>NULL</literal>. Function
1568     <function>ZOOM_connection_error_x</function> is an extended version
1569     of <function>ZOOM_connection_error</function> that is capable of
1570     returning name of diagnostic set in <parameter>dset</parameter>.
1571    </para>
1572    <sect2 id="zoom-connection-z39.50">
1573     <title>Z39.50 Protocol behavior</title>
1574     <para>
1575      The calls <function>ZOOM_connection_new</function> and
1576      <function>ZOOM_connection_connect</function> establishes a TCP/IP
1577      connection and sends an Initialize Request to the target if
1578      possible. In addition, the calls waits for an Initialize Response
1579      from the target and the result is inspected (OK or rejected).
1580     </para>
1581     <para>
1582      If <literal>proxy</literal> is set then the client will establish
1583      a TCP/IP connection with the peer as specified by the
1584      <literal>proxy</literal> host and the hostname as part of the
1585      connect calls will be set as part of the Initialize Request.
1586      The proxy server will then "forward" the PDU's transparently
1587      to the target behind the proxy.
1588     </para>
1589     <para>
1590      For the authentication parameters, if option <literal>user</literal>
1591      is set and both options <literal>group</literal> and
1592      <literal>pass</literal> are unset, then Open style
1593      authentication is used (Version 2/3) in which case the username
1594      is usually followed by a slash, then by a password.
1595      If either <literal>group</literal>
1596      or <literal>pass</literal> is set then idPass authentication
1597      (Version 3 only) is used. If none of the options are set, no
1598      authentication parameters are set as part of the Initialize Request
1599      (obviously).
1600     </para>
1601     <para>
1602      When option <literal>async</literal> is 1, it really means that
1603      all network operations are postponed (and queued) until the
1604      function <literal>ZOOM_event</literal> is invoked. When doing so
1605      it doesn't make sense to check for errors after
1606      <literal>ZOOM_connection_new</literal> is called since that
1607      operation "connecting - and init" is still incomplete and the
1608      API cannot tell the outcome (yet).
1609     </para>
1610     </sect2>
1611    <sect2 id="zoom.sru.init.behavior">
1612     <title>SRU/Solr Protocol behavior</title>
1613     <para>
1614      The HTTP based protocols (SRU, SRW, Solr) doesn't feature an
1615      Inititialize Request, so  the connection phase merely establishes a
1616      TCP/IP connection with the HTTP server.
1617     </para>
1618     <para>Most of the ZOOM connection options do not
1619      affect SRU/Solr and they are ignored. However, future versions
1620      of &yaz; might honor <literal>implementationName</literal> and
1621      put that as part of User-Agent header for HTTP requests.
1622      </para>
1623     <para>
1624      The <literal>charset</literal> is used in the Content-Type header
1625      of HTTP requests.
1626     </para>
1627     <para>
1628      Setting <literal>authentcationMode</literal> specifies how
1629      authentication parameters are encoded for HTTP. The default is
1630      "<literal>basic</literal>" where <literal>user</literal> and
1631      <literal>password</literal> are encoded by using HTTP basic
1632      authentication.
1633      </para>
1634     <para>
1635      If <literal>authentcationMode</literal> is "<literal>url</literal>", then
1636      user and password are encoded in the URL by parameters
1637      <literal>x-username</literal> and <literal>x-password</literal> as
1638      given by the SRU standard.
1639     </para>
1640    </sect2>
1641   </sect1>
1642   <sect1 id="zoom.query">
1643    <title>Queries</title>
1644    <para>
1645     Query objects represents queries.
1646    </para>
1647    <synopsis>
1648      ZOOM_query ZOOM_query_create(void);
1649
1650      void ZOOM_query_destroy(ZOOM_query q);
1651
1652      int ZOOM_query_prefix(ZOOM_query q, const char *str);
1653
1654      int ZOOM_query_cql(ZOOM_query s, const char *str);
1655
1656      int ZOOM_query_sortby(ZOOM_query q, const char *criteria);
1657
1658      int ZOOM_query_sortby2(ZOOM_query q, const char *strategy,
1659                             const char *criteria);
1660    </synopsis>
1661    <para>
1662     Create query objects using <function>ZOOM_query_create</function>
1663     and destroy them by calling <function>ZOOM_query_destroy</function>.
1664     RPN-queries can be specified in <link linkend="PQF">PQF</link>
1665     notation by using the
1666     function <function>ZOOM_query_prefix</function>.
1667     The <function>ZOOM_query_cql</function> specifies a CQL
1668     query to be sent to the server/target.
1669     More query types will be added in future versions of &yaz;, such as
1670     <link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
1671     etc. In addition to a search, a sort criteria may be set. Function
1672     <function>ZOOM_query_sortby</function> enables Z39.50 sorting and
1673     it takes sort criteria using the same string notation as
1674     yaz-client's <link linkend="sortspec">sort command</link>.
1675    </para>
1676    <para id="zoom.query.sortby2">
1677     <function>ZOOM_query_sortby2</function> is similar to
1678     <function>ZOOM_query_sortby</function> but allows a strategy for
1679     sorting. The reason for the strategy parameter is that some
1680     protocols offers multiple ways of performing sorting.
1681     For example, Z39.50 has the standard sort, which is performed after
1682     search on an existing result set.
1683     It's also possible to use CQL in Z39.50 as the query type and use
1684     CQL's SORTBY keyword. Finally, Index Data's
1685     Zebra server also allows sorting to be specified as part of RPN (Type 7).
1686    </para>
1687    <table id="zoom-sort-strategy" frame="top">
1688     <title>ZOOM sort strategy</title>
1689     <tgroup cols="2">
1690      <colspec colwidth="2*" colname="name"/>
1691      <colspec colwidth="5*" colname="description"/>
1692      <thead>
1693       <row>
1694        <entry>Name</entry>
1695        <entry>Description</entry>
1696       </row>
1697      </thead>
1698      <tbody>
1699       <row>
1700        <entry>z39.50</entry><entry>Z39.50 resultset sort</entry>
1701       </row>
1702       <row>
1703        <entry>type7</entry><entry>Sorting embedded in RPN(Type-7)</entry>
1704       </row>
1705       <row>
1706        <entry>cql</entry><entry>CQL SORTBY</entry>
1707       </row>
1708       <row>
1709        <entry>sru11</entry><entry>SRU sortKeys parameter</entry>
1710       </row>
1711       <row>
1712        <entry>solr</entry><entry>Solr sort</entry>
1713       </row>
1714       <row>
1715        <entry>embed</entry><entry>type7 for Z39.50, cql for SRU,
1716         solr for Solr protocol</entry>
1717       </row>
1718      </tbody>
1719     </tgroup>
1720    </table>
1721   </sect1>
1722   <sect1 id="zoom.resultsets"><title>Result sets</title>
1723    <para>
1724     The result set object is a container for records returned from
1725     a target.
1726    </para>
1727    <synopsis>
1728      ZOOM_resultset ZOOM_connection_search(ZOOM_connection, ZOOM_query q);
1729
1730      ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c,
1731                                                const char *q);
1732      void ZOOM_resultset_destroy(ZOOM_resultset r);
1733    </synopsis>
1734    <para>
1735     Function <function>ZOOM_connection_search</function> creates
1736     a result set given a connection and query.
1737     Destroy a result set by calling
1738     <function>ZOOM_resultset_destroy</function>.
1739     Simple clients may using PQF only may use function
1740     <function>ZOOM_connection_search_pqf</function> in which case
1741     creating query objects is not necessary.
1742    </para>
1743    <synopsis>
1744      void ZOOM_resultset_option_set(ZOOM_resultset r,
1745                                     const char *key, const char *val);
1746
1747      const char *ZOOM_resultset_option_get(ZOOM_resultset r, const char *key);
1748
1749      size_t ZOOM_resultset_size(ZOOM_resultset r);
1750    </synopsis>
1751    <para>
1752     Functions <function>ZOOM_resultset_options_set</function> and
1753     <function>ZOOM_resultset_get</function> sets and gets an option
1754     for a result set similar to <function>ZOOM_connection_option_get</function>
1755     and <function>ZOOM_connection_option_set</function>.
1756    </para>
1757    <para>
1758     The number of hits also called result-count is returned by
1759     function <function>ZOOM_resultset_size</function>.
1760    </para>
1761    <table id="zoom.resultset.options"
1762     frame="top"><title>ZOOM Result set Options</title>
1763     <tgroup cols="3">
1764      <colspec colwidth="4*" colname="name"></colspec>
1765      <colspec colwidth="7*" colname="description"></colspec>
1766      <colspec colwidth="2*" colname="default"></colspec>
1767      <thead>
1768       <row>
1769        <entry>Option</entry>
1770        <entry>Description</entry>
1771        <entry>Default</entry>
1772       </row>
1773      </thead>
1774      <tbody>
1775       <row><entry>
1776         start</entry><entry>Offset of first record to be
1777         retrieved from target. First record has offset 0 unlike the
1778         protocol specifications where first record has position 1.
1779         This option affects ZOOM_resultset_search and
1780         ZOOM_resultset_search_pqf and must be set before any of
1781         these functions are invoked. If a range of
1782         records must be fetched manually after search,
1783         function ZOOM_resultset_records should be used.
1784        </entry><entry>0</entry></row>
1785       <row><entry>
1786         count</entry><entry>Number of records to be retrieved.
1787         This option affects ZOOM_resultset_search and
1788         ZOOM_resultset_search_pqf and must be set before any of
1789         these functions are invoked.
1790        </entry><entry>0</entry></row>
1791       <row><entry>
1792         presentChunk</entry><entry>The number of records to be
1793         requested from the server in each chunk (present request). The
1794         value 0 means to request all the records in a single chunk.
1795         (The old <literal>step</literal>
1796         option is also supported for the benefit of old applications.)
1797        </entry><entry>0</entry></row>
1798       <row><entry>
1799         elementSetName</entry><entry>Element-Set name of records.
1800         Most targets should honor element set name <literal>B</literal>
1801         and <literal>F</literal> for brief and full respectively.
1802        </entry><entry>none</entry></row>
1803       <row><entry>
1804         preferredRecordSyntax</entry><entry>Preferred Syntax, such as
1805         <literal>USMARC</literal>, <literal>SUTRS</literal>, etc.
1806        </entry><entry>none</entry></row>
1807       <row><entry>
1808         schema</entry><entry>Schema for retrieval, such as
1809         <literal>Gils-schema</literal>, <literal>Geo-schema</literal>, etc.
1810        </entry><entry>none</entry></row>
1811       <row><entry>
1812         setname</entry><entry>Name of Result Set (Result Set ID).
1813         If this option isn't set, the ZOOM module will automatically
1814         allocate a result set name.
1815        </entry><entry>default</entry></row>
1816       <row><entry>
1817         rpnCharset</entry><entry>Character set for RPN terms.
1818         If this is set, ZOOM C will assume that the ZOOM application is
1819         running UTF-8. Terms in RPN queries are then converted to the
1820         rpnCharset. If this is unset, ZOOM C will not assume any encoding
1821         of RPN terms and no conversion is performed.
1822        </entry><entry>none</entry></row>
1823      </tbody>
1824     </tgroup>
1825    </table>
1826    <para>
1827     For servers that support Search Info report, the following
1828     options may be read using <function>ZOOM_resultset_get</function>.
1829     This detailed information is read after a successful search has
1830     completed.
1831    </para>
1832    <para>
1833     This information is a list of of items, where each item is
1834     information about a term or subquery. All items in the list
1835     are prefixed by
1836     <literal>SearchResult.</literal><replaceable>no</replaceable>
1837     where no presents the item number (0=first, 1=second).
1838     Read <literal>searchresult.size</literal> to determine the
1839     number of items.
1840    </para>
1841    <table id="zoom.search.info.report.options"
1842     frame="top"><title>Search Info Report Options</title>
1843     <tgroup cols="2">
1844      <colspec colwidth="4*" colname="name"></colspec>
1845      <colspec colwidth="7*" colname="description"></colspec>
1846      <thead>
1847       <row>
1848        <entry>Option</entry>
1849        <entry>Description</entry>
1850       </row>
1851      </thead>
1852      <tbody>
1853       <row>
1854        <entry>searchresult.size</entry>
1855        <entry>
1856         number of search result entries. This option is-nonexistant
1857         if no entries are returned by the server.
1858        </entry>
1859       </row>
1860       <row>
1861        <entry>searchresult.<replaceable>no</replaceable>.id</entry>
1862        <entry>sub query ID</entry>
1863       </row>
1864       <row>
1865        <entry>searchresult.<replaceable>no</replaceable>.count</entry>
1866        <entry>result count for item (number of hits)</entry>
1867       </row>
1868       <row>
1869        <entry>searchresult.<replaceable>no</replaceable>.subquery.term</entry>
1870        <entry>subquery term</entry>
1871       </row>
1872       <row>
1873        <entry>
1874         searchresult.<replaceable>no</replaceable>.interpretation.term
1875        </entry>
1876        <entry>interpretation term</entry>
1877       </row>
1878       <row>
1879        <entry>
1880         searchresult.<replaceable>no</replaceable>.recommendation.term
1881        </entry>
1882        <entry>recommendation term</entry>
1883       </row>
1884      </tbody>
1885     </tgroup>
1886    </table>
1887    <sect2 id="zoom.z3950.resultset.sort">
1888     <title>Z39.50 Result-set Sort</title>
1889     <synopsis>
1890      void ZOOM_resultset_sort(ZOOM_resultset r,
1891                               const char *sort_type, const char *sort_spec);
1892
1893      int ZOOM_resultset_sort1(ZOOM_resultset r,
1894                               const char *sort_type, const char *sort_spec);
1895     </synopsis>
1896     <para>
1897      <function>ZOOM_resultset_sort</function> and
1898      <function>ZOOM_resultset_sort1</function> both sort an existing
1899      result-set. The sort_type parameter is not use. Set it to "yaz".
1900      The sort_spec is same notation as ZOOM_query_sortby and identical
1901      to that offered by yaz-client's
1902      <link linkend="sortspec">sort command</link>.
1903     </para>
1904     <para>
1905      These functions only work for Z39.50. Use the more generic utility
1906      <link linkend="zoom.query.sortby2">
1907       <function>ZOOM_query_sortby2</function></link>
1908      for other protocols (and even Z39.50).
1909     </para>
1910    </sect2>
1911    <sect2 id="zoom.z3950.resultset.behavior">
1912     <title>Z39.50 Protocol behavior</title>
1913     <para>
1914      The creation of a result set involves at least a SearchRequest
1915      - SearchResponse protocol handshake. Following that, if a sort
1916      criteria was specified as part of the query, a SortRequest -
1917      SortResponse handshake takes place. Note that it is necessary to
1918      perform sorting before any retrieval takes place, so no records will
1919      be returned from the target as part of the SearchResponse because these
1920      would be unsorted. Hence, piggyback is disabled when sort criteria
1921      are set. Following Search - and a possible sort - Retrieval takes
1922      place - as one or more Present Requests/Response pairs being
1923      transferred.
1924      </para>
1925     <para>
1926      The API allows for two different modes for retrieval. A high level
1927      mode which is somewhat more powerful and a low level one.
1928      The low level is enabled when searching on a Connection object
1929      for which the settings
1930      <literal>smallSetUpperBound</literal>,
1931      <literal>mediumSetPresentNumber</literal> and
1932      <literal>largeSetLowerBound</literal> are set. The low level mode
1933      thus allows you to precisely set how records are returned as part
1934      of a search response as offered by the Z39.50 protocol.
1935      Since the client may be retrieving records as part of the
1936      search response, this mode doesn't work well if sorting is used.
1937      </para>
1938     <para>
1939      The high-level mode allows you to fetch a range of records from
1940      the result set with a given start offset. When you use this mode
1941      the client will automatically use piggyback if that is possible
1942      with the target and perform one or more present requests as needed.
1943      Even if the target returns fewer records as part of a present response
1944      because of a record size limit, etc. the client will repeat sending
1945      present requests. As an example, if option <literal>start</literal>
1946      is 0 (default) and <literal>count</literal> is 4, and
1947      <literal>piggyback</literal> is 1 (default) and no sorting criteria
1948      is specified, then the client will attempt to retrieve the 4
1949      records as part the search response (using piggyback). On the other
1950      hand, if either <literal>start</literal> is positive or if
1951      a sorting criteria is set, or if <literal>piggyback</literal>
1952      is 0, then the client will not perform piggyback but send Present
1953      Requests instead.
1954     </para>
1955     <para>
1956      If either of the options <literal>mediumSetElementSetName</literal> and
1957      <literal>smallSetElementSetName</literal> are unset, the value
1958      of option <literal>elementSetName</literal> is used for piggyback
1959      searches. This means that for the high-level mode you only have
1960      to specify one elementSetName option rather than three.
1961      </para>
1962    </sect2>
1963    <sect2 id="zoom.sru.resultset.behavior">
1964     <title>SRU Protocol behavior</title>
1965     <para>
1966      Current version of &yaz; does not take advantage of a result set id
1967      returned by the SRU server. Future versions might do, however.
1968      Since, the ZOOM driver does not save result set IDs any
1969      present (retrieval) is transformed to a SRU SearchRetrieveRequest
1970      with same query but, possibly, different offsets.
1971     </para>
1972     <para>
1973      Option <literal>schema</literal> specifies SRU schema
1974      for retrieval. However, options <literal>elementSetName</literal> and
1975      <literal>preferredRecordSyntax</literal> are ignored.
1976     </para>
1977     <para>
1978      Options <literal>start</literal> and <literal>count</literal>
1979      are supported by SRU.
1980      The remaining options
1981      <literal>piggyback</literal>,
1982      <literal>smallSetUpperBound</literal>,
1983      <literal>largeSetLowerBound</literal>,
1984      <literal>mediumSetPresentNumber</literal>,
1985      <literal>mediumSetElementSetName</literal>,
1986       <literal>smallSetElementSetName</literal> are
1987      unsupported.
1988     </para>
1989     <para>
1990      SRU supports CQL queries, <emphasis>not</emphasis> PQF.
1991      If PQF is used, however, the PQF query is transferred anyway
1992      using non-standard element <literal>pQuery</literal> in
1993      SRU SearchRetrieveRequest.
1994     </para>
1995     <para>
1996      Solr queries has to be done in Solr query format.
1997     </para>
1998     <para>
1999      Unfortunately, SRU or Solr does not define a database setting. Hence,
2000      <literal>databaseName</literal> is unsupported and ignored.
2001      However, the path part in host parameter for functions
2002      <function>ZOOM_connecton_new</function> and
2003      <function>ZOOM_connection_connect</function> acts as a
2004      database (at least for the &yaz; SRU server).
2005     </para>
2006    </sect2>
2007   </sect1>
2008   <sect1 id="zoom.records">
2009    <title>Records</title>
2010    <para>
2011     A record object is a retrieval record on the client side -
2012     created from result sets.
2013    </para>
2014    <synopsis>
2015      void ZOOM_resultset_records(ZOOM_resultset r,
2016                                  ZOOM_record *recs,
2017                                  size_t start, size_t count);
2018      ZOOM_record ZOOM_resultset_record(ZOOM_resultset s, size_t pos);
2019
2020      const char *ZOOM_record_get(ZOOM_record rec, const char *type,
2021                                  size_t *len);
2022
2023      int ZOOM_record_error(ZOOM_record rec, const char **msg,
2024                            const char **addinfo, const char **diagset);
2025
2026      ZOOM_record ZOOM_record_clone(ZOOM_record rec);
2027
2028      void ZOOM_record_destroy(ZOOM_record rec);
2029    </synopsis>
2030    <para>
2031     References to temporary records are returned by functions
2032     <function>ZOOM_resultset_records</function> or
2033     <function>ZOOM_resultset_record</function>.
2034     </para>
2035    <para>
2036     If a persistent reference to a record is desired
2037     <function>ZOOM_record_clone</function> should be used.
2038     It returns a record reference that should be destroyed
2039     by a call to <function>ZOOM_record_destroy</function>.
2040    </para>
2041    <para>
2042     A single record is returned by function
2043     <function>ZOOM_resultset_record</function> that takes a
2044     position as argument. First record has position zero.
2045     If no record could be obtained <literal>NULL</literal> is returned.
2046    </para>
2047    <para>
2048     Error information for a record can be checked with
2049     <function>ZOOM_record_error</function> which returns non-zero
2050     (error code) if record is in error, called <emphasis>Surrogate
2051      Diagnostics</emphasis> in Z39.50.
2052    </para>
2053    <para>
2054     Function <function>ZOOM_resultset_records</function> retrieves
2055     a number of records from a result set. Parameter <literal>start</literal>
2056     and <literal>count</literal> specifies the range of records to
2057     be returned. Upon completion array
2058     <literal>recs[0], ..recs[count-1]</literal>
2059     holds record objects for the records. The array of records
2060      <literal>recs</literal> should be allocated prior the call
2061     <function>ZOOM_resultset_records</function>. Note that for those
2062     records that couldn't be retrieved from the target
2063     <literal>recs[ ..]</literal> is set to <literal>NULL</literal>.
2064    </para>
2065    <para id="zoom.record.get">
2066     In order to extract information about a single record,
2067     <function>ZOOM_record_get</function> is provided. The
2068     function returns a pointer to certain record information. The
2069     nature (type) of the pointer depends on the parameter,
2070     <parameter>type</parameter>.
2071    </para>
2072    <para>
2073     The <parameter>type</parameter> is a string of the format:
2074    </para>
2075    <para>
2076     <replaceable>format</replaceable>[;charset=<replaceable>from</replaceable>[/<replaceable>opacfrom</replaceable>][,<replaceable>to</replaceable>]][;format=<replaceable>v</replaceable>]
2077    </para>
2078    <para>
2079     where <replaceable>format</replaceable> specifies the format of the
2080     returned record, <replaceable>from</replaceable>
2081     specifies the character set of the record in its original form
2082     (as returned by the server), <replaceable>to</replaceable> specifies
2083     the output (returned)
2084     character set encoding.
2085     If <replaceable>to</replaceable> is omitted UTF-8 is assumed.
2086     If charset is not given, then no character set conversion takes place.
2087    </para>
2088
2089    <para>OPAC records may be returned in a different
2090      set from the bibliographic MARC record. If this is this the case,
2091     <replaceable>opacfrom</replaceable> should be set to the character set
2092     of the OPAC record part.
2093    </para>
2094    <note>
2095      <para>
2096        Specifying the OPAC record character set requires YAZ 4.1.5 or later.
2097      </para>
2098    </note>
2099    <para>
2100     The format argument controls whether record data should be XML
2101     pretty-printed (post process operation).
2102     It is enabled only if format value <replaceable>v</replaceable> is
2103     <literal>1</literal> and the record content is XML well-formed.
2104    </para>
2105    <para>
2106     In addition, for certain types, the length
2107     <literal>len</literal> passed will be set to the size in bytes of
2108     the returned information.
2109     </para>
2110    <para>
2111     The following are the supported values for <replaceable>form</replaceable>.
2112     <variablelist>
2113      <varlistentry><term><literal>database</literal></term>
2114       <listitem><para>Database of record is returned
2115         as a C null-terminated string. Return type
2116         <literal>const char *</literal>.
2117        </para></listitem>
2118      </varlistentry>
2119      <varlistentry><term><literal>syntax</literal></term>
2120       <listitem><para>The transfer syntax of the record is returned
2121         as a C null-terminated string containing the symbolic name of
2122         the record syntax, e.g. <literal>Usmarc</literal>. Return type
2123         is
2124         <literal>const char *</literal>.
2125        </para></listitem>
2126      </varlistentry>
2127      <varlistentry><term><literal>schema</literal></term>
2128       <listitem><para>The schema of the record is returned
2129         as a C null-terminated string. Return type is
2130         <literal>const char *</literal>.
2131        </para></listitem>
2132      </varlistentry>
2133      <varlistentry><term><literal>render</literal></term>
2134       <listitem><para>The record is returned in a display friendly
2135         format. Upon completion buffer is returned
2136         (type <literal>const char *</literal>) and length is stored in
2137         <literal>*len</literal>.
2138        </para></listitem>
2139      </varlistentry>
2140      <varlistentry><term><literal>raw</literal></term>
2141       <listitem><para>The record is returned in the internal
2142         YAZ specific format. For GRS-1, Explain, and others, the
2143         raw data is returned as type
2144         <literal>Z_External *</literal> which is just the type for
2145         the member <literal>retrievalRecord</literal> in
2146         type <literal>NamePlusRecord</literal>.
2147         For SUTRS and octet aligned record (including all MARCs) the
2148         octet buffer is returned and the length of the buffer.
2149        </para></listitem>
2150      </varlistentry>
2151      <varlistentry><term><literal>xml</literal></term>
2152       <listitem><para>The record is returned in XML if possible.
2153         SRU, Solr and Z39.50 records with transfer syntax XML are
2154         returned verbatim. MARC records are returned in
2155         <ulink url="&url.marcxml;">
2156          MARCXML
2157          </ulink>
2158         (converted from ISO2709 to MARCXML by YAZ).
2159         OPAC records are also converted to XML and the
2160         bibliographic record is converted to MARCXML (when possible).
2161         GRS-1 records are not supported for this form.
2162         Upon completion, the XML buffer is returned
2163         (type <literal>const char *</literal>) and length is stored in
2164         <literal>*len</literal>.
2165        </para></listitem>
2166      </varlistentry>
2167      <varlistentry><term><literal>opac</literal></term>
2168       <listitem><para>OPAC information for record is returned in XML
2169         if an OPAC record is present at the position given. If no
2170         OPAC record is present, a NULL pointer is returned.
2171        </para></listitem>
2172      </varlistentry>
2173      <varlistentry><term><literal>txml</literal></term>
2174       <listitem><para>The record is returned in TurboMARC if possible.
2175         SRU and Z39.50 records with transfer syntax XML are
2176         returned verbatim. MARC records are returned in
2177         <link linkend="tools.turbomarc">
2178          TurboMARC
2179         </link>
2180         (converted from ISO2709 to TurboMARC by YAZ).
2181         Upon completion, the XML buffer is returned
2182         (type <literal>const char *</literal>) and length is stored in
2183         <literal>*len</literal>.
2184        </para></listitem>
2185      </varlistentry>
2186      <varlistentry><term><literal>json</literal></term>
2187       <listitem><para>Like xml, but MARC records are converted to
2188         <ulink url="&url.marc_in_json;">MARC-in-JSON</ulink>.
2189        </para></listitem>
2190      </varlistentry>
2191
2192     </variablelist>
2193    </para>
2194    <para>
2195     Most
2196     <ulink url="&url.marc21;">MARC21</ulink>
2197     records uses the
2198     <ulink url="&url.marc8;">MARC-8</ulink>
2199     character set encoding.
2200     An application that wishes to display in Latin-1 would use
2201     <screen>
2202      render; charset=marc8,iso-8859-1
2203     </screen>
2204    </para>
2205    <sect2 id="zoom.z3950.record.behavior">
2206     <title>Z39.50 Protocol behavior</title>
2207     <para>
2208      The functions <function>ZOOM_resultset_record</function> and
2209      <function>ZOOM_resultset_records</function> inspects the client-side
2210      record cache. Records not found in cache are fetched using
2211      Present.
2212      The functions may block (and perform network I/O)  - even though option
2213      <literal>async</literal> is 1, because they return records objects.
2214      (and there's no way to return records objects without retrieving them!).
2215      </para>
2216     <para>
2217      There is a trick, however, in the usage of function
2218      <function>ZOOM_resultset_records</function> that allows for
2219      delayed retrieval (and makes it non-blocking). By using
2220      a null pointer for <parameter>recs</parameter> you're indicating
2221      you're not interested in getting records objects
2222      <emphasis>now</emphasis>.
2223     </para>
2224    </sect2>
2225    <sect2 id="zoom.sru.record.behavior">
2226     <title>SRU/Solr Protocol behavior</title>
2227     <para>
2228      The ZOOM driver for SRU/Solr treats records returned by a SRU/Solr server
2229      as if they where Z39.50 records with transfer syntax XML and
2230      no element set name or database name.
2231     </para>
2232    </sect2>
2233   </sect1>
2234   <sect1 id="zoom.facets"><title>Facets</title>
2235    <para>
2236     Facet operations is not part of the official ZOOM specification, but
2237     is an Index Data extension for YAZ-based Z39.50 targets,
2238     <ulink url="&url.solr;">Solr</ulink> and SRU 2.0 targets.
2239
2240     Facets may be requestd by the
2241      <link linkend="zoom.facets.option">facets</link> option before a
2242     search is sent.
2243     For inspection of the returned facets, the following functions are
2244     available:
2245    </para>
2246    <synopsis>
2247     ZOOM_facet_field *ZOOM_resultset_facets(ZOOM_resultset r);
2248
2249     ZOOM_facet_field ZOOM_resultset_get_facet_field(ZOOM_resultset r,
2250                                                     const char *facet_name);
2251
2252     ZOOM_facet_field ZOOM_resultset_get_facet_field_by_index(ZOOM_resultset r,
2253                                                              int pos);
2254
2255     size_t ZOOM_resultset_facets_size(ZOOM_resultset r);
2256
2257     const char *ZOOM_facet_field_name(ZOOM_facet_field facet_field);
2258
2259     size_t ZOOM_facet_field_term_count(ZOOM_facet_field facet_field);
2260
2261     const char *ZOOM_facet_field_get_term(ZOOM_facet_field facet_field,
2262                                           size_t idx, int *freq);
2263    </synopsis>
2264    <para>
2265     References to temporary structures are returned by all functions.
2266     They are only valid as long the Result set is valid.
2267     <function>ZOOM_resultset_get_facet_field</function> or
2268     <function>ZOOM_resultset_get_facet_field_by_index</function>.
2269     <function>ZOOM_resultset_facets</function>.
2270     <function>ZOOM_facet_field_name</function>.
2271     <function>ZOOM_facet_field_get_term</function>.
2272     </para>
2273    <para id="zoom.resultset.get_facet_field">
2274     A single Facet field  is returned by function
2275     <function>ZOOM_resultset_get_facet_field</function> or
2276     <function>ZOOM_resultset_get_facet_field_by_index</function> that takes
2277     a  result set and facet name or positive index respectively. First
2278     facet has position zero. If no facet could be obtained (invalid name
2279     or index out of bounds) <literal>NULL</literal> is returned.
2280    </para>
2281    <para id="zoom.resultset.facets">
2282     An array of facets field can be returned by
2283     <function>ZOOM_resultset_facets</function>. The length of the array is
2284     given by <function>ZOOM_resultset_facets_size</function>. The array is
2285     zero-based and last entry will be at
2286     <function>ZOOM_resultset_facets_size(result_set)</function>-1.
2287    </para>
2288    <para id="zoom.resultset.facets_names">
2289     It is possible to interate over facets by name, by calling
2290     <function>ZOOM_resultset_facets_names</function>.
2291     This will return an const array of char * where each string can be used
2292     as parameter for <function>ZOOM_resultset_get_facet_field</function>.
2293    </para>
2294    <para>
2295    Function <function>ZOOM_facet_field_name</function> gets the request
2296     facet name from a returned facet field.
2297    </para>
2298    <para>
2299     Function <function>ZOOM_facet_field_get_term</function> returns the
2300     idx'th term and term count for a facet field.
2301     Idx must between 0 and
2302     <function>ZOOM_facet_field_term_count</function>-1, otherwise the
2303     returned reference will be <literal>NULL</literal>. On a valid idx, the
2304     value of the freq reference will be the term count.
2305     The <literal>freq</literal> parameter must be valid pointer to integer.
2306    </para>
2307    </sect1>
2308   <sect1 id="zoom.scan"><title>Scan</title>
2309    <para>
2310     This section describes an interface for Scan. Scan is not an
2311     official part of the ZOOM model yet. The result of a scan operation
2312     is the <literal>ZOOM_scanset</literal> which is a set of terms
2313     returned by a target.
2314    </para>
2315
2316    <para>
2317     The Scan interface is supported for both Z39.50, SRU and Solr.
2318    </para>
2319
2320    <synopsis>
2321     ZOOM_scanset ZOOM_connection_scan(ZOOM_connection c,
2322                                       const char *startpqf);
2323
2324     ZOOM_scanset ZOOM_connection_scan1(ZOOM_connection c,
2325                                        ZOOM_query q);
2326
2327     size_t ZOOM_scanset_size(ZOOM_scanset scan);
2328
2329     const char *ZOOM_scanset_term(ZOOM_scanset scan, size_t pos,
2330                                   size_t *occ, size_t *len);
2331
2332     const char *ZOOM_scanset_display_term(ZOOM_scanset scan, size_t pos,
2333                                           size_t *occ, size_t *len);
2334
2335     void ZOOM_scanset_destroy(ZOOM_scanset scan);
2336
2337     const char *ZOOM_scanset_option_get(ZOOM_scanset scan,
2338                                         const char *key);
2339
2340     void ZOOM_scanset_option_set(ZOOM_scanset scan, const char *key,
2341                                  const char *val);
2342     </synopsis>
2343    <para>
2344     The scan set is created by function
2345     <function>ZOOM_connection_scan</function> which performs a scan
2346     operation on the connection using the specified
2347     <parameter>startpqf</parameter>.
2348     If the operation was successful, the size of the scan set can be
2349     retrieved by a call to <function>ZOOM_scanset_size</function>.
2350     Like result sets, the items are numbered 0,..size-1.
2351     To obtain information about a particular scan term, call function
2352     <function>ZOOM_scanset_term</function>. This function takes
2353     a scan set offset <literal>pos</literal> and returns a pointer
2354     to a <emphasis>raw term</emphasis> or <literal>NULL</literal> if
2355     non-present.
2356     If present, the <literal>occ</literal> and <literal>len</literal>
2357     are set to the number of occurrences and the length
2358     of the actual term respectively.
2359     <function>ZOOM_scanset_display_term</function> is similar to
2360     <function>ZOOM_scanset_term</function> except that it returns
2361     the <emphasis>display term</emphasis> rather than the raw term.
2362     In a few cases, the term is different from display term. Always
2363     use the display term for display and the raw term for subsequent
2364     scan operations (to get more terms, next scan result, etc).
2365    </para>
2366    <para>
2367     A scan set may be freed by a call to function
2368     <function>ZOOM_scanset_destroy</function>.
2369     Functions <function>ZOOM_scanset_option_get</function> and
2370     <function>ZOOM_scanset_option_set</function> retrieves and sets
2371     an option respectively.
2372    </para>
2373    <para>
2374     The <parameter>startpqf</parameter> is a subset of PQF, namely
2375     the Attributes+Term part. Multiple <literal>@attr</literal> can
2376     be used. For example to scan in title (complete) phrases:
2377     <literallayout>
2378      @attr 1=4 @attr 6=2 "science o"
2379     </literallayout>
2380    </para>
2381    <para>
2382     The <function>ZOOM_connecton_scan1</function> is a newer and
2383     more generic alternative to <function>ZOOM_connection_scan</function>
2384     which allows to use both CQL and PQF for Scan.
2385    </para>
2386    <table frame="top" id="zoom.scanset.options">
2387     <title>ZOOM Scan Set Options</title>
2388     <tgroup cols="3">
2389      <colspec colwidth="4*" colname="name"></colspec>
2390      <colspec colwidth="7*" colname="description"></colspec>
2391      <colspec colwidth="2*" colname="default"></colspec>
2392      <thead>
2393       <row>
2394        <entry>Option</entry>
2395        <entry>Description</entry>
2396        <entry>Default</entry>
2397       </row>
2398      </thead>
2399      <tbody>
2400       <row><entry>
2401         number</entry><entry>Number of Scan Terms requested in next scan.
2402         After scan it holds the actual number of terms returned.
2403        </entry><entry>20</entry></row>
2404       <row><entry>
2405         position</entry><entry>Preferred Position of term in response
2406         in next scan; actual position after completion of scan.
2407        </entry><entry>1</entry></row>
2408       <row><entry>
2409         stepSize</entry><entry>Step Size
2410        </entry><entry>0</entry></row>
2411       <row><entry>
2412         scanStatus</entry><entry>An integer indicating the Scan Status
2413         of last scan.
2414        </entry><entry>0</entry></row>
2415       <row><entry>
2416         rpnCharset</entry><entry>Character set for RPN terms.
2417         If this is set, ZOOM C will assume that the ZOOM application is
2418         running UTF-8. Terms in RPN queries are then converted to the
2419         rpnCharset. If this is unset, ZOOM C will not assume any encoding
2420         of RPN terms and no conversion is performed.
2421        </entry><entry>none</entry></row>
2422      </tbody>
2423     </tgroup>
2424    </table>
2425   </sect1>
2426   <sect1 id="zoom.extendedservices">
2427    <title>Extended Services</title>
2428    <para>
2429     ZOOM offers an interface to a subset of the Z39.50 extended services
2430     as well as a few privately defined ones:
2431    </para>
2432    <itemizedlist>
2433     <listitem>
2434      <para>
2435       Z39.50 Item Order (ILL).
2436       See <xref linkend="zoom.item.order"/>.
2437      </para>
2438     </listitem>
2439     <listitem>
2440      <para>
2441       Record Update. This allows a client to insert, modify or delete
2442       records.
2443       See <xref linkend="zoom.record.update"/>.
2444      </para>
2445     </listitem>
2446     <listitem>
2447      <para>
2448       Database Create. This a non-standard feature. Allows a client
2449       to create a database.
2450       See <xref linkend="zoom.database.create"/>.
2451      </para>
2452     </listitem>
2453     <listitem>
2454      <para>
2455       Database Drop. This a non-standard feature. Allows a client
2456       to delete/drop a database.
2457       See <xref linkend="zoom.database.drop"/>.
2458      </para>
2459      </listitem>
2460     <listitem>
2461      <para>
2462       Commit operation. This a non-standard feature. Allows a client
2463       to commit operations.
2464       See <xref linkend="zoom.commit"/>.
2465      </para>
2466     </listitem>
2467     <!-- all the ILL PDU options should go here too -->
2468    </itemizedlist>
2469    <para>
2470     To create an extended service operation a <literal>ZOOM_package</literal>
2471     must be created. The operation is a five step operation. The
2472     package is created, package is configured by means of options,
2473     the package is send, result is inspected (by means of options),
2474     the package is destroyed.
2475    </para>
2476    <synopsis>
2477     ZOOM_package ZOOM_connection_package(ZOOM_connection c,
2478                                          ZOOM_options options);
2479
2480     const char *ZOOM_package_option_get(ZOOM_package p,
2481                                         const char *key);
2482     void ZOOM_package_option_set(ZOOM_package p, const char *key,
2483                                  const char *val);
2484     void ZOOM_package_send(ZOOM_package p, const char *type);
2485
2486     void ZOOM_package_destroy(ZOOM_package p);
2487    </synopsis>
2488    <para>
2489     The <function>ZOOM_connection_package</function> creates a
2490     package for the connection given using the options specified.
2491    </para>
2492    <para>
2493     Functions <function>ZOOM_package_option_get</function> and
2494     <function>ZOOM_package_option_set</function> gets and sets
2495     options.
2496    </para>
2497    <para>
2498     <function>ZOOM_package_send</function> sends
2499     the package the via connection specified in
2500     <function>ZOOM_connection_package</function>.
2501     The <parameter>type</parameter> specifies the actual extended service
2502     package type to be sent.
2503    </para>
2504    <table frame="top" id="zoom.extendedservices.options">
2505     <title>Extended Service Common Options</title>
2506     <tgroup cols="3">
2507      <colspec colwidth="4*" colname="name"></colspec>
2508      <colspec colwidth="7*" colname="description"></colspec>
2509      <colspec colwidth="3*" colname="default"></colspec>
2510      <thead>
2511       <row>
2512        <entry>Option</entry>
2513        <entry>Description</entry>
2514        <entry>Default</entry>
2515       </row>
2516      </thead>
2517      <tbody>
2518       <row>
2519        <entry>package-name</entry>
2520        <entry>Extended Service Request package name. Must be specified
2521        as part of a request</entry>
2522        <entry>none</entry>
2523       </row>
2524       <row>
2525        <entry>user-id</entry>
2526        <entry>User ID of Extended Service Package. Is a request option</entry>
2527        <entry>none</entry>
2528       </row>
2529       <row>
2530        <entry>function</entry>
2531        <entry>
2532         Function of package - one of <literal>create</literal>,
2533         <literal>delete</literal>, <literal>modify</literal>. Is
2534         a request option.
2535        </entry>
2536        <entry><literal>create</literal></entry>
2537       </row>
2538       <row>
2539        <entry>waitAction</entry>
2540        <entry>
2541         Wait action for package. Possible values:
2542         <literal>wait</literal>, <literal>waitIfPossible</literal>,
2543         <literal>dontWait</literal> or <literal>dontReturnPackage</literal>.
2544        </entry>
2545        <entry><literal>waitIfPossible</literal></entry>
2546       </row>
2547       <row>
2548        <entry>targetReference</entry>
2549        <entry>
2550         Target Reference. This is part of the response as returned
2551         by the server. Read it after a successful operation.
2552        </entry>
2553        <entry><literal>none</literal></entry>
2554       </row>
2555      </tbody>
2556     </tgroup>
2557    </table>
2558    <sect2 id="zoom.item.order">
2559     <title>Item Order</title>
2560     <para>
2561      For Item Order, type must be set to <literal>itemorder</literal> in
2562      <function>ZOOM_package_send</function>.
2563     </para>
2564
2565     <table frame="top" id="zoom.item.order.options">
2566      <title>Item Order Options</title>
2567      <tgroup cols="3">
2568       <colspec colwidth="4*" colname="name"></colspec>
2569       <colspec colwidth="7*" colname="description"></colspec>
2570       <colspec colwidth="3*" colname="default"></colspec>
2571       <thead>
2572        <row>
2573         <entry>Option</entry>
2574         <entry>Description</entry>
2575         <entry>Default</entry>
2576        </row>
2577       </thead>
2578       <tbody>
2579        <row>
2580         <entry>contact-name</entry>
2581         <entry>ILL contact name</entry>
2582         <entry>none</entry>
2583        </row>
2584        <row>
2585         <entry>contact-phone</entry>
2586         <entry>ILL contact phone</entry>
2587         <entry>none</entry>
2588        </row>
2589        <row>
2590         <entry>contact-email</entry>
2591         <entry>ILL contact email</entry>
2592         <entry>none</entry>
2593        </row>
2594        <row>
2595         <entry>itemorder-item</entry>
2596         <entry>Position for item (record) requested. An integer</entry>
2597         <entry>1</entry>
2598        </row>
2599       </tbody>
2600      </tgroup>
2601     </table>
2602    </sect2>
2603    <sect2 id="zoom.record.update">
2604     <title>Record Update</title>
2605     <para>
2606      For Record Update, type must be set to <literal>update</literal> in
2607      <function>ZOOM_package_send</function>.
2608     </para>
2609     <table frame="top" id="zoom.record.update.options">
2610      <title>Record Update Options</title>
2611      <tgroup cols="3">
2612       <colspec colwidth="4*" colname="name"></colspec>
2613       <colspec colwidth="7*" colname="description"></colspec>
2614       <colspec colwidth="3*" colname="default"></colspec>
2615       <thead>
2616        <row>
2617         <entry>Option</entry>
2618         <entry>Description</entry>
2619         <entry>Default</entry>
2620        </row>
2621       </thead>
2622       <tbody>
2623        <row>
2624         <entry>action</entry>
2625         <entry>
2626          The update action. One of
2627          <literal>specialUpdate</literal>,
2628          <literal>recordInsert</literal>,
2629          <literal>recordReplace</literal>,
2630          <literal>recordDelete</literal>,
2631          <literal>elementUpdate</literal>.
2632         </entry>
2633         <entry><literal>specialUpdate (recordInsert for updateVersion=1 which does not support specialUpdate)</literal></entry>
2634        </row>
2635        <row>
2636         <entry>recordIdOpaque</entry>
2637         <entry>Opaque Record ID</entry>
2638         <entry>none</entry>
2639        </row>
2640        <row>
2641         <entry>recordIdNumber</entry>
2642         <entry>Record ID number</entry>
2643         <entry>none</entry>
2644        </row>
2645        <row>
2646         <entry>record</entry>
2647         <entry>The record itself</entry>
2648         <entry>none</entry>
2649        </row>
2650        <row>
2651         <entry>recordOpaque</entry>
2652         <entry>Specifies an opaque record which is
2653           encoded as an ASN.1 ANY type with the OID as tiven by option
2654           <literal>syntax</literal> (see below).
2655           Option <literal>recordOpaque</literal> is an alternative
2656           to record - and <literal>record</literal> option (above) is
2657           ignored if recordOpaque is set. This option is only available in
2658           YAZ 3.0.35 and later and is meant to facilitate Updates with
2659           servers from OCLC.
2660         </entry>
2661         <entry>none</entry>
2662        </row>
2663        <row>
2664         <entry>syntax</entry>
2665         <entry>The record syntax (transfer syntax). Is a string that
2666          is a known record syntax.
2667         </entry>
2668         <entry>no syntax</entry>
2669        </row>
2670        <row>
2671         <entry>databaseName</entry>
2672         <entry>Database from connection object</entry>
2673         <entry>Default</entry>
2674        </row>
2675        <row>
2676         <entry>correlationInfo.note</entry>
2677         <entry>Correlation Info Note (string)</entry>
2678         <entry>none</entry>
2679        </row>
2680        <row>
2681         <entry>correlationInfo.id</entry>
2682         <entry>Correlation Info ID (integer)</entry>
2683         <entry>none</entry>
2684        </row>
2685        <row>
2686         <entry>elementSetName</entry>
2687         <entry>Element Set for Record</entry>
2688         <entry>none</entry>
2689        </row>
2690        <row>
2691         <entry>updateVersion</entry>
2692         <entry>Record Update version which holds one of the values
2693          1, 2 or 3. Each version has a distinct OID:
2694          1.2.840.10003.9.5
2695          (<ulink url="&url.z39.50.extupdate1;">first version</ulink>) ,
2696          1.2.840.10003.9.5.1
2697          (second version) and
2698          1.2.840.10003.9.5.1.1
2699          (<ulink url="&url.z39.50.extupdate3;">third and
2700           newest version</ulink>).
2701         </entry>
2702         <entry>3</entry>
2703        </row>
2704       </tbody>
2705      </tgroup>
2706     </table>
2707
2708    </sect2>
2709
2710    <sect2 id="zoom.database.create"><title>Database Create</title>
2711     <para>
2712      For Database Create, type must be set to <literal>create</literal> in
2713      <function>ZOOM_package_send</function>.
2714     </para>
2715
2716     <table frame="top" id="zoom.database.create.options">
2717      <title>Database Create Options</title>
2718      <tgroup cols="3">
2719       <colspec colwidth="4*" colname="name"></colspec>
2720       <colspec colwidth="7*" colname="description"></colspec>
2721       <colspec colwidth="3*" colname="default"></colspec>
2722       <thead>
2723        <row>
2724         <entry>Option</entry>
2725         <entry>Description</entry>
2726         <entry>Default</entry>
2727        </row>
2728       </thead>
2729       <tbody>
2730        <row>
2731         <entry>databaseName</entry>
2732         <entry>Database from connection object</entry>
2733         <entry>Default</entry>
2734        </row>
2735       </tbody>
2736      </tgroup>
2737     </table>
2738    </sect2>
2739    <sect2 id="zoom.database.drop">
2740     <title>Database Drop</title>
2741     <para>
2742      For Database Drop, type must be set to <literal>drop</literal> in
2743      <function>ZOOM_package_send</function>.
2744     </para>
2745     <table frame="top" id="zoom.database.drop.options">
2746      <title>Database Drop 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.commit">
2769     <title>Commit Operation</title>
2770     <para>
2771      For Commit, type must be set to <literal>commit</literal> in
2772      <function>ZOOM_package_send</function>.
2773     </para>
2774    </sect2>
2775    <sect2 id="zoom.extended.services.behavior">
2776     <title>Protocol behavior</title>
2777     <para>
2778      All the extended services are Z39.50-only.
2779     </para>
2780     <note>
2781      <para>
2782       The database create, drop and commit services are privately defined
2783       operations.
2784       Refer to <filename>esadmin.asn</filename> in YAZ for the ASN.1
2785       definitions.
2786      </para>
2787     </note>
2788    </sect2>
2789   </sect1>
2790   <sect1 id="zoom.options">
2791    <title>Options</title>
2792    <para>
2793     Most &zoom; objects provide a way to specify options to change behavior.
2794     From an implementation point of view a set of options is just like
2795     an associative array / hash.
2796    </para>
2797    <synopsis>
2798      ZOOM_options ZOOM_options_create(void);
2799
2800      ZOOM_options ZOOM_options_create_with_parent(ZOOM_options parent);
2801
2802      void ZOOM_options_destroy(ZOOM_options opt);
2803    </synopsis>
2804    <synopsis>
2805      const char *ZOOM_options_get(ZOOM_options opt, const char *name);
2806
2807      void ZOOM_options_set(ZOOM_options opt, const char *name,
2808                            const char *v);
2809    </synopsis>
2810    <synopsis>
2811      typedef const char *(*ZOOM_options_callback)
2812                             (void *handle, const char *name);
2813
2814      ZOOM_options_callback
2815              ZOOM_options_set_callback(ZOOM_options opt,
2816                                        ZOOM_options_callback c,
2817                                        void *handle);
2818    </synopsis>
2819   </sect1>
2820   <sect1 id="zoom.queryconversions">
2821    <title>Query conversions</title>
2822    <synopsis>
2823     int ZOOM_query_cql2rpn(ZOOM_query s, const char *cql_str,
2824                            ZOOM_connection conn);
2825
2826     int ZOOM_query_ccl2rpn(ZOOM_query s, const char *ccl_str,
2827                            const char *config,
2828                            int *ccl_error, const char **error_string,
2829                            int *error_pos);
2830    </synopsis>
2831    <para>
2832     <function>ZOOM_query_cql2rpn</function> translates the CQL string,
2833     client-side, into RPN which may be passed to the server.
2834     This is useful for server's that don't themselves
2835     support CQL, for which <function>ZOOM_query_cql</function> is useless.
2836     `conn' is used  only as a place to stash diagnostics if compilation
2837     fails; if this information is not needed, a null pointer may be used.
2838     The CQL conversion is driven by option <literal>cqlfile</literal> from
2839     connection conn. This specifies a conversion file (eg pqf.properties)
2840     which <emphasis>must</emphasis> be present.
2841    </para>
2842    <para>
2843     <function>ZOOM_query_ccl2rpn</function> translates the CCL string,
2844     client-side, into RPN which may be passed to the server.
2845     The conversion is driven by the specification given by
2846     <literal>config</literal>. Upon completion 0 is returned on success; -1
2847     is returned on on failure. Om failure <literal>error_string</literal> and
2848     <literal>error_pos</literal> holds error message and position of
2849     first error in original CCL string.
2850    </para>
2851   </sect1>
2852   <sect1 id="zoom.events"><title>Events</title>
2853    <para>
2854     If you're developing non-blocking applications, you have to deal
2855     with events.
2856    </para>
2857    <synopsis>
2858     int ZOOM_event(int no, ZOOM_connection *cs);
2859    </synopsis>
2860    <para>
2861     The <function>ZOOM_event</function> executes pending events for
2862     a number of connections. Supply the number of connections in
2863     <literal>no</literal> and an array of connections in
2864     <literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
2865     A pending event could be a sending a search, receiving a response,
2866     etc.
2867     When an event has occurred for one of the connections, this function
2868     returns a positive integer <literal>n</literal> denoting that an event
2869     occurred for connection <literal>cs[n-1]</literal>.
2870     When no events are pending for the connections, a value of zero is
2871     returned.
2872     To ensure that all outstanding requests are performed call this function
2873     repeatedly until zero is returned.
2874    </para>
2875    <para>
2876     If <function>ZOOM_event</function> returns and returns non-zero, the
2877     last event that occurred can be expected.
2878    </para>
2879    <synopsis>
2880     int ZOOM_connection_last_event(ZOOM_connection cs);
2881    </synopsis>
2882    <para>
2883     <function>ZOOM_connection_last_event</function> returns an event type
2884     (integer) for the last event.
2885    </para>
2886
2887    <table frame="top" id="zoom.event.ids">
2888     <title>ZOOM Event IDs</title>
2889     <tgroup cols="2">
2890      <colspec colwidth="4*" colname="name"></colspec>
2891      <colspec colwidth="7*" colname="description"></colspec>
2892      <thead>
2893       <row>
2894        <entry>Event</entry>
2895        <entry>Description</entry>
2896       </row>
2897      </thead>
2898      <tbody>
2899       <row>
2900        <entry>ZOOM_EVENT_NONE</entry>
2901        <entry>No event has occurred</entry>
2902       </row>
2903       <row>
2904        <entry>ZOOM_EVENT_CONNECT</entry>
2905        <entry>TCP/IP connect has initiated</entry>
2906       </row>
2907       <row>
2908        <entry>ZOOM_EVENT_SEND_DATA</entry>
2909        <entry>Data has been transmitted (sending)</entry>
2910       </row>
2911       <row>
2912        <entry>ZOOM_EVENT_RECV_DATA</entry>
2913        <entry>Data has been received)</entry>
2914       </row>
2915       <row>
2916        <entry>ZOOM_EVENT_TIMEOUT</entry>
2917        <entry>Timeout</entry>
2918       </row>
2919       <row>
2920        <entry>ZOOM_EVENT_UNKNOWN</entry>
2921        <entry>Unknown event</entry>
2922       </row>
2923       <row>
2924        <entry>ZOOM_EVENT_SEND_APDU</entry>
2925        <entry>An APDU has been transmitted (sending)</entry>
2926       </row>
2927       <row>
2928        <entry>ZOOM_EVENT_RECV_APDU</entry>
2929        <entry>An APDU has been received</entry>
2930       </row>
2931       <row>
2932        <entry>ZOOM_EVENT_RECV_RECORD</entry>
2933        <entry>A result-set record has been received</entry>
2934       </row>
2935       <row>
2936        <entry>ZOOM_EVENT_RECV_SEARCH</entry>
2937        <entry>A search result been received</entry>
2938       </row>
2939      </tbody>
2940     </tgroup>
2941    </table>
2942   </sect1>
2943  </chapter>
2944  <chapter id="server">
2945   <title>Generic server</title>
2946   <sect1 id="server.introduction"><title>Introduction</title>
2947    <para>
2948     If you aren't into documentation, a good way to learn how the
2949     back end interface works is to look at the <filename>backend.h</filename>
2950     file. Then, look at the small dummy-server in
2951     <filename>ztest/ztest.c</filename>. The <filename>backend.h</filename>
2952     file also makes a good reference, once you've chewed your way through
2953     the prose of this file.
2954    </para>
2955    <para>
2956     If you have a database system that you would like to make available by
2957     means of Z39.50 or SRU, &yaz; basically offers your two options. You
2958     can use the APIs provided by the &asn;, &odr;, and &comstack;
2959     modules to
2960     create and decode PDUs, and exchange them with a client.
2961     Using this low-level interface gives you access to all fields and
2962     options of the protocol, and you can construct your server as close
2963     to your existing database as you like.
2964     It is also a fairly involved process, requiring
2965     you to set up an event-handling mechanism, protocol state machine,
2966     etc. To simplify server implementation, we have implemented a compact
2967     and simple, but reasonably full-functioned server-frontend that will
2968     handle most of the protocol mechanics, while leaving you to
2969     concentrate on your database interface.
2970    </para>
2971    <note>
2972     <para>
2973      The backend interface was designed in anticipation of a specific
2974      integration task, while still attempting to achieve some degree of
2975      generality. We realize fully that there are points where the
2976      interface can be improved significantly. If you have specific
2977      functions or parameters that you think could be useful, send us a
2978      mail (or better, sign on to the mailing list referred to in the
2979      top-level README file). We will try to fit good suggestions into future
2980      releases, to the extent that it can be done without requiring
2981      too many structural changes in existing applications.
2982     </para>
2983    </note>
2984    <note>
2985     <para>
2986      The &yaz; server does not support XCQL.
2987      </para>
2988    </note>
2989   </sect1>
2990   <sect1 id="server.frontend">
2991    <title>The Database Frontend</title>
2992    <para>
2993     We refer to this software as a generic database frontend. Your
2994     database system is the <emphasis>backend database</emphasis>, and the
2995     interface between the two is called the <emphasis>backend API</emphasis>.
2996     The backend API consists of a small number of function handlers and
2997     structure definitions. You are required to provide the
2998     <function>main()</function> routine for the server (which can be
2999     quite simple), as well as a set of handlers to match each of the
3000     prototypes.
3001     The interface functions that you write can use any mechanism you like
3002     to communicate with your database system: You might link the whole
3003     thing together with your database application and access it by
3004     function calls; you might use IPC to talk to a database server
3005     somewhere; or you might link with third-party software that handles
3006     the communication for you (like a commercial database client library).
3007     At any rate, the handlers will perform the tasks of:
3008    </para>
3009    <itemizedlist>
3010     <listitem><para>
3011      Initialization.
3012     </para></listitem>
3013     <listitem><para>
3014      Searching.
3015     </para></listitem>
3016     <listitem><para>
3017      Fetching records.
3018     </para></listitem>
3019     <listitem><para>
3020      Scanning the database index (optional - if you wish to implement SCAN).
3021     </para></listitem>
3022     <listitem><para>
3023      Extended Services (optional).
3024     </para></listitem>
3025     <listitem><para>
3026      Result-Set Delete (optional).
3027     </para></listitem>
3028     <listitem><para>
3029      Result-Set Sort (optional).
3030     </para></listitem>
3031     <listitem><para>
3032      Return Explain for SRU (optional).
3033     </para></listitem>
3034    </itemizedlist>
3035    <para>
3036     (more functions will be added in time to support as much of
3037     Z39.50-1995 as possible).
3038    </para>
3039   </sect1>
3040   <sect1 id="server.backend">
3041    <title>The Backend API</title>
3042    <para>
3043     The header file that you need to use the interface are in the
3044     <filename>include/yaz</filename> directory. It's called
3045     <filename>backend.h</filename>. It will include other files from
3046     the <filename>include/yaz</filename> directory, so you'll
3047     probably want to use the -I option of your compiler to tell it
3048     where to find the files. When you run
3049     <literal>make</literal> in the top-level &yaz; directory,
3050     everything you need to create your server is to link with the
3051     <filename>lib/libyaz.la</filename> library.
3052    </para>
3053   </sect1>
3054   <sect1 id="server.main">
3055    <title>Your main() Routine</title>
3056    <para>
3057     As mentioned, your <function>main()</function> routine can be quite brief.
3058     If you want to initialize global parameters, or read global configuration
3059     tables, this is the place to do it. At the end of the routine, you should
3060     call the function
3061    </para>
3062    <synopsis>
3063 int statserv_main(int argc, char **argv,
3064                   bend_initresult *(*bend_init)(bend_initrequest *r),
3065                   void (*bend_close)(void *handle));
3066    </synopsis>
3067    <para>
3068     The third and fourth arguments are pointers to handlers. Handler
3069     <function>bend_init</function> is called whenever the server receives
3070     an Initialize Request, so it serves as a Z39.50 session initializer. The
3071     <function>bend_close</function> handler is called when the session is
3072     closed.
3073    </para>
3074    <para>
3075     <function>statserv_main</function> will establish listening sockets
3076     according to the parameters given. When connection requests are received,
3077     the event handler will typically <function>fork()</function> and
3078     create a sub-process to handle a new connection.
3079     Alternatively the server may be setup to create threads for each
3080     connection.
3081     If you do use global variables and forking, you should be aware, then,
3082     that these cannot be shared between associations, unless you explicitly
3083     disable forking by command line parameters.
3084    </para>
3085    <para>
3086     The server provides a mechanism for controlling some of its behavior
3087     without using command-line options. The function
3088    </para>
3089    <synopsis>
3090     statserv_options_block *statserv_getcontrol(void);
3091    </synopsis>
3092    <para>
3093     will return a pointer to a <literal>struct statserv_options_block</literal>
3094     describing the current default settings of the server. The structure
3095     contains these elements:
3096     <variablelist>
3097      <varlistentry>
3098       <term><literal>int dynamic</literal></term>
3099       <listitem><para>
3100        A boolean value, which determines whether the server
3101        will fork on each incoming request (TRUE), or not (FALSE). Default is
3102        TRUE. This flag is only read by UNIX-based servers (WIN32 based servers
3103        doesn't fork).
3104      </para></listitem>
3105      </varlistentry>
3106      <varlistentry>
3107       <term><literal>int threads</literal></term>
3108       <listitem><para>
3109        A boolean value, which determines whether the server
3110        will create a thread on each incoming request (TRUE), or not (FALSE).
3111        Default is FALSE. This flag is only read by UNIX-based servers
3112        that offer POSIX Threads support.
3113        WIN32-based servers always operate in threaded mode.
3114      </para></listitem>
3115      </varlistentry>
3116      <varlistentry>
3117       <term><literal>int inetd</literal></term>
3118       <listitem><para>
3119        A boolean value, which determines whether the server
3120        will operates under a UNIX INET daemon (inetd). Default is FALSE.
3121      </para></listitem>
3122      </varlistentry>
3123      <varlistentry>
3124       <term><literal>char logfile[ODR_MAXNAME+1]</literal></term>
3125       <listitem><para>File for diagnostic output (&quot;&quot;: stderr).
3126      </para></listitem>
3127      </varlistentry>
3128      <varlistentry>
3129       <term><literal>char apdufile[ODR_MAXNAME+1]</literal></term>
3130       <listitem><para>
3131        Name of file for logging incoming and outgoing APDUs
3132        (&quot;&quot;: don't log APDUs, &quot;-&quot;:
3133        <literal>stderr</literal>).
3134      </para></listitem>
3135      </varlistentry>
3136      <varlistentry>
3137       <term><literal>char default_listen[1024]</literal></term>
3138       <listitem><para>Same form as the command-line specification of
3139       listener address. &quot;&quot;: no default listener address.
3140       Default is to listen at &quot;tcp:@:9999&quot;. You can only
3141       specify one default listener address in this fashion.
3142      </para></listitem>
3143      </varlistentry>
3144      <varlistentry>
3145       <term><literal>enum oid_proto default_proto;</literal></term>
3146       <listitem><para>Either <literal>PROTO_Z3950</literal> or
3147       <literal>PROTO_SR</literal>.
3148       Default is <literal>PROTO_Z39_50</literal>.
3149      </para></listitem>
3150      </varlistentry>
3151      <varlistentry>
3152       <term><literal>int idle_timeout;</literal></term>
3153       <listitem><para>Maximum session idle-time, in minutes. Zero indicates
3154       no (infinite) timeout. Default is 15 minutes.
3155      </para></listitem>
3156      </varlistentry>
3157      <varlistentry>
3158       <term><literal>int maxrecordsize;</literal></term>
3159       <listitem><para>Maximum permissible record (message) size. Default
3160       is 64 MB. This amount of memory will only be allocated if a
3161       client requests a very large amount of records in one operation
3162       (or a big record).
3163       Set it to a lower number if you are worried about resource
3164       consumption on your host system.
3165      </para></listitem>
3166      </varlistentry>
3167      <varlistentry>
3168       <term><literal>char configname[ODR_MAXNAME+1]</literal></term>
3169       <listitem><para>Passed to the backend when a new connection is received.
3170      </para></listitem>
3171      </varlistentry>
3172      <varlistentry>
3173       <term><literal>char setuid[ODR_MAXNAME+1]</literal></term>
3174       <listitem><para>Set user id to the user specified, after binding
3175       the listener addresses.
3176      </para></listitem>
3177      </varlistentry>
3178      <varlistentry>
3179       <term>
3180        <literal>void (*bend_start)(struct statserv_options_block *p)</literal>
3181       </term>
3182       <listitem><para>Pointer to function which is called after the
3183       command line options have been parsed - but before the server
3184       starts listening.
3185       For forked UNIX servers this handler is called in the mother
3186       process; for threaded servers this handler is called in the
3187       main thread.
3188       The default value of this pointer is NULL in which case it
3189       isn't invoked by the frontend server.
3190       When the server operates as an NT service this handler is called
3191       whenever the service is started.
3192       </para></listitem>
3193      </varlistentry>
3194      <varlistentry>
3195       <term>
3196        <literal>void (*bend_stop)(struct statserv_options_block *p)</literal>
3197       </term>
3198       <listitem><para>Pointer to function which is called whenever the server
3199       has stopped listening for incoming connections. This function pointer
3200       has a default value of NULL in which case it isn't called.
3201       When the server operates as an NT service this handler is called
3202       whenever the service is stopped.
3203       </para></listitem>
3204      </varlistentry>
3205      <varlistentry>
3206       <term><literal>void *handle</literal></term>
3207       <listitem><para>User defined pointer (default value NULL).
3208       This is a per-server handle that can be used to specify "user-data".
3209       Do not confuse this with the session-handle as returned by bend_init.
3210       </para></listitem>
3211      </varlistentry>
3212     </variablelist>
3213    </para>
3214    <para>
3215     The pointer returned by <literal>statserv_getcontrol</literal> points to
3216     a static area. You are allowed to change the contents of the structure,
3217     but the changes will not take effect before you call
3218    </para>
3219    <synopsis>
3220 void statserv_setcontrol(statserv_options_block *block);
3221    </synopsis>
3222    <note>
3223     <para>
3224      that you should generally update this structure before calling
3225      <function>statserv_main()</function>.
3226     </para>
3227    </note>
3228   </sect1>
3229   <sect1 id="server.backendfunctions">
3230    <title>The Backend Functions</title>
3231    <para>
3232     For each service of the protocol, the backend interface declares one or
3233     two functions. You are required to provide implementations of the
3234     functions representing the services that you wish to implement.
3235    </para>
3236    <sect2 id="server.init">
3237     <title>Init</title>
3238     <synopsis>
3239 bend_initresult (*bend_init)(bend_initrequest *r);
3240     </synopsis>
3241     <para>
3242      This handler is called once for each new connection request, after
3243      a new process/thread has been created, and an Initialize Request has
3244      been received from the client. The pointer to the
3245      <function>bend_init</function> handler is passed in the call to
3246      <function>statserv_start</function>.
3247     </para>
3248     <para>
3249      This handler is also called when operating in SRU mode - when
3250      a connection has been made (even though SRU does not offer
3251      this service).
3252     </para>
3253     <para>
3254      Unlike previous versions of YAZ, the <function>bend_init</function> also
3255      serves as a handler that defines the Z39.50 services that the backend
3256      wish to support. Pointers to <emphasis>all</emphasis> service handlers,
3257      including search - and fetch must be specified here in this handler.
3258     </para>
3259     <para>
3260      The request - and result structures are defined as
3261     </para>
3262     <synopsis>
3263 typedef struct bend_initrequest
3264 {
3265     /** \brief user/name/password to be read */
3266     Z_IdAuthentication *auth;
3267     /** \brief encoding stream (for results) */
3268     ODR stream;
3269     /** \brief printing stream */
3270     ODR print;
3271     /** \brief decoding stream (use stream for results) */
3272     ODR decode;
3273     /** \brief reference ID */
3274     Z_ReferenceId *referenceId;
3275     /** \brief peer address of client */
3276     char *peer_name;
3277
3278     /** \brief character set and language negotiation
3279
3280     see include/yaz/z-charneg.h
3281     */
3282     Z_CharSetandLanguageNegotiation *charneg_request;
3283
3284     /** \brief character negotiation response */
3285     Z_External *charneg_response;
3286
3287     /** \brief character set (encoding) for query terms
3288
3289     This is NULL by default. It should be set to the native character
3290     set that the backend assumes for query terms */
3291     char *query_charset;
3292
3293     /** \brief whehter query_charset also applies to recors
3294
3295     Is 0 (No) by default. Set to 1 (yes) if records is in the same
3296     character set as queries. If in doubt, use 0 (No).
3297     */
3298     int records_in_same_charset;
3299
3300     char *implementation_id;
3301     char *implementation_name;
3302     char *implementation_version;
3303
3304     /** \brief Z39.50 sort handler */
3305     int (*bend_sort)(void *handle, bend_sort_rr *rr);
3306     /** \brief SRU/Z39.50 search handler */
3307     int (*bend_search)(void *handle, bend_search_rr *rr);
3308     /** \brief SRU/Z39.50 fetch handler */
3309     int (*bend_fetch)(void *handle, bend_fetch_rr *rr);
3310     /** \brief SRU/Z39.50 present handler */
3311     int (*bend_present)(void *handle, bend_present_rr *rr);
3312     /** \brief Z39.50 extended services handler */
3313     int (*bend_esrequest) (void *handle, bend_esrequest_rr *rr);
3314     /** \brief Z39.50 delete result set handler */
3315     int (*bend_delete)(void *handle, bend_delete_rr *rr);
3316     /** \brief Z39.50 scan handler */
3317     int (*bend_scan)(void *handle, bend_scan_rr *rr);
3318     /** \brief Z39.50 segment facility handler */
3319     int (*bend_segment)(void *handle, bend_segment_rr *rr);
3320     /** \brief SRU explain handler */
3321     int (*bend_explain)(void *handle, bend_explain_rr *rr);
3322     /** \brief SRU scan handler */
3323     int (*bend_srw_scan)(void *handle, bend_scan_rr *rr);
3324     /** \brief SRU record update handler */
3325     int (*bend_srw_update)(void *handle, bend_update_rr *rr);
3326
3327     /** \brief whether named result sets are supported (0=disable, 1=enable) */
3328     int named_result_sets;
3329 } bend_initrequest;
3330
3331 typedef struct bend_initresult
3332 {
3333     int errcode;               /* 0==OK */
3334     char *errstring;           /* system error string or NULL */
3335     void *handle;              /* private handle to the backend module */
3336 } bend_initresult;
3337     </synopsis>
3338     <para>
3339      In general, the server frontend expects that the
3340      <literal>bend_*result</literal> pointer that you return is valid at
3341      least until the next call to a <literal>bend_* function</literal>.
3342      This applies to all of the functions described herein. The parameter
3343      structure passed to you in the call belongs to the server frontend, and
3344      you should not make assumptions about its contents after the current
3345      function call has completed. In other words, if you want to retain any
3346      of the contents of a request structure, you should copy them.
3347     </para>
3348     <para>
3349      The <literal>errcode</literal> should be zero if the initialization of
3350      the backend went well. Any other value will be interpreted as an error.
3351      The <literal>errstring</literal> isn't used in the current version, but
3352      one option would be to stick it in the initResponse as a VisibleString.
3353      The <literal>handle</literal> is the most important parameter. It should
3354      be set to some value that uniquely identifies the current session to
3355      the backend implementation. It is used by the frontend server in any
3356      future calls to a backend function.
3357      The typical use is to set it to point to a dynamically allocated state
3358      structure that is private to your backend module.
3359     </para>
3360     <para>
3361      The <literal>auth</literal> member holds the authentication information
3362      part of the Z39.50 Initialize Request. Interpret this if your serves
3363      requires authentication.
3364     </para>
3365     <para>
3366      The members <literal>peer_name</literal>,
3367      <literal>implementation_id</literal>,
3368      <literal>implementation_name</literal> and
3369      <literal>implementation_version</literal> holds
3370      DNS of client, ID of implementor, name
3371      of client (Z39.50) implementation - and version.
3372     </para>
3373     <para>
3374      The <literal>bend_</literal> - members are set to NULL when
3375      <function>bend_init</function> is called. Modify the pointers by
3376      setting them to point to backend functions.
3377     </para>
3378    </sect2>
3379    <sect2 id="server.search.retrieve">
3380     <title>Search and Retrieve</title>
3381     <para>
3382      We now describe the handlers that are required to support search -
3383      and retrieve. You must support two functions - one for search - and one
3384      for fetch (retrieval of one record). If desirable you can provide a
3385      third handler which is called when a present request is received which
3386      allows you to optimize retrieval of multiple-records.
3387     </para>
3388     <synopsis>
3389 int (*bend_search) (void *handle, bend_search_rr *rr);
3390
3391 typedef struct {
3392     char *setname;             /* name to give to this set */
3393     int replace_set;           /* replace set, if it already exists */
3394     int num_bases;             /* number of databases in list */
3395     char **basenames;          /* databases to search */
3396     Z_ReferenceId *referenceId;/* reference ID */
3397     Z_Query *query;            /* query structure */
3398     ODR stream;                /* encode stream */
3399     ODR decode;                /* decode stream */
3400     ODR print;                 /* print stream */
3401
3402     bend_request request;
3403     bend_association association;
3404     int *fd;
3405     int hits;                  /* number of hits */
3406     int errcode;               /* 0==OK */
3407     char *errstring;           /* system error string or NULL */
3408     Z_OtherInformation *search_info; /* additional search info */
3409     char *srw_sortKeys;        /* holds SRU/SRW sortKeys info */
3410     char *srw_setname;         /* holds SRU/SRW generated resultsetID */
3411     int *srw_setnameIdleTime;  /* holds SRU/SRW life-time */
3412     int estimated_hit_count;   /* if hit count is estimated */
3413     int partial_resultset;     /* if result set is partial */
3414 } bend_search_rr;
3415     </synopsis>
3416     <para>
3417      The <function>bend_search</function> handler is a fairly close
3418      approximation of a protocol Z39.50 Search Request - and Response PDUs
3419      The <literal>setname</literal> is the resultSetName from the protocol.
3420      You are required to establish a mapping between the set name and whatever
3421      your backend database likes to use.
3422      Similarly, the <literal>replace_set</literal> is a boolean value
3423      corresponding to the resultSetIndicator field in the protocol.
3424      <literal>num_bases/basenames</literal> is a length of/array of character
3425      pointers to the database names provided by the client.
3426      The <literal>query</literal> is the full query structure as defined in
3427      the protocol ASN.1 specification.
3428      It can be either of the possible query types, and it's up to you to
3429      determine if you can handle the provided query type.
3430      Rather than reproduce the C interface here, we'll refer you to the
3431      structure definitions in the file
3432      <filename>include/yaz/z-core.h</filename>. If you want to look at the
3433      attributeSetId OID of the RPN query, you can either match it against
3434      your own internal tables, or you can use the <link linkend="tools.oid">
3435      OID tools</link>.
3436     </para>
3437     <para>
3438      The structure contains a number of hits, and an
3439      <literal>errcode/errstring</literal> pair. If an error occurs
3440      during the search, or if you're unhappy with the request, you should
3441      set the errcode to a value from the BIB-1 diagnostic set. The value
3442      will then be returned to the user in a nonsurrogate diagnostic record
3443      in the response. The <literal>errstring</literal>, if provided, will
3444      go in the addinfo field. Look at the protocol definition for the
3445      defined error codes, and the suggested uses of the addinfo field.
3446     </para>
3447     <para>
3448      The <function>bend_search</function> handler is also called when
3449      the frontend server receives a SRU SearchRetrieveRequest.
3450      For SRU, a CQL query is usually provided by the client.
3451      The CQL query is available as part of <literal>Z_Query</literal>
3452      structure (note that CQL is now part of Z39.50 via an external).
3453      To support CQL in existing implementations that only do Type-1,
3454      we refer to the CQL-to-PQF tool described
3455      <link linkend="cql.to.pqf">here</link>.
3456     </para>
3457     <para>
3458      To maintain backwards compatibility, the frontend server
3459      of yaz always assume that error codes are BIB-1 diagnostics.
3460      For SRU operation, a Bib-1 diagnostic code is mapped to
3461      SRU diagnostic.
3462     </para>
3463     <synopsis>
3464 int (*bend_fetch) (void *handle, bend_fetch_rr *rr);
3465
3466 typedef struct bend_fetch_rr {
3467     char *setname;             /* set name */
3468     int number;                /* record number */
3469     Z_ReferenceId *referenceId;/* reference ID */
3470     Odr_oid *request_format;        /* format, transfer syntax (OID) */
3471     Z_RecordComposition *comp; /* Formatting instructions */
3472     ODR stream;                /* encoding stream - memory source if req */
3473     ODR print;                 /* printing stream */
3474
3475     char *basename;            /* name of database that provided record */
3476     int len;                   /* length of record or -1 if structured */
3477     char *record;              /* record */
3478     int last_in_set;           /* is it?  */
3479     Odr_oid *output_format;        /* response format/syntax (OID) */
3480     int errcode;               /* 0==success */
3481     char *errstring;           /* system error string or NULL */
3482     int surrogate_flag;        /* surrogate diagnostic */
3483     char *schema;              /* string record schema input/output */
3484 } bend_fetch_rr;
3485     </synopsis>
3486     <para>
3487      The frontend server calls the <function>bend_fetch</function> handler
3488      when it needs database records to fulfill a Z39.50 Search Request, a
3489      Z39.50 Present Request or a SRU SearchRetrieveRequest.
3490      The <literal>setname</literal> is simply the name of the result set
3491      that holds the reference to the desired record.
3492      The <literal>number</literal> is the offset into the set (with 1
3493      being the first record in the set). The <literal>format</literal> field
3494      is the record format requested by the client (See
3495      <xref linkend="tools.oid"/>).
3496      A value of NULL for <literal>format</literal> indicates that the
3497      client did not request a specific format.
3498      The <literal>stream</literal> argument is an &odr; stream which
3499      should be used for allocating space for structured data records.
3500      The stream will be reset when all records have been assembled, and
3501      the response package has been transmitted.
3502      For unstructured data, the backend is responsible for maintaining a
3503      static or dynamic buffer for the record between calls.
3504     </para>
3505     <para>
3506      If a SRU SearchRetrieveRequest is received by the frontend server,
3507      the <literal>referenceId</literal> is NULL and the
3508      <literal>format</literal> (transfer syntax) is the OID for XML.
3509      The schema for SRU is stored in both the
3510      <literal>Z_RecordComposition</literal>
3511      structure and <literal>schema</literal> (simple string).
3512     </para>
3513     <para>
3514      In the structure, the <literal>basename</literal> is the name of the
3515      database that holds the
3516      record. <literal>len</literal> is the length of the record returned, in
3517      bytes, and <literal>record</literal> is a pointer to the record.
3518      <literal>last_in_set</literal> should be nonzero only if the record
3519      returned is the last one in the given result set.
3520      <literal>errcode</literal> and <literal>errstring</literal>, if
3521      given, will be interpreted as a global error pertaining to the
3522      set, and will be returned in a non-surrogate-diagnostic.
3523      If you wish to return the error as a surrogate-diagnostic
3524      (local error) you can do this by setting
3525      <literal>surrogate_flag</literal> to 1 also.
3526     </para>
3527     <para>
3528      If the <literal>len</literal> field has the value -1, then
3529      <literal>record</literal> is assumed to point to a constructed data
3530      type. The <literal>format</literal> field will be used to determine
3531      which encoder should be used to serialize the data.
3532     </para>
3533     <note>
3534      <para>
3535       If your backend generates structured records, it should use
3536       <function>odr_malloc()</function> on the provided stream for allocating
3537       data: This allows the frontend server to keep track of the record sizes.
3538      </para>
3539     </note>
3540     <para>
3541      The <literal>format</literal> field is mapped to an object identifier
3542      in the direct reference of the resulting EXTERNAL representation
3543      of the record.
3544     </para>
3545     <note>
3546      <para>
3547       The current version of &yaz; only supports the direct reference mode.
3548      </para>
3549     </note>
3550     <synopsis>
3551 int (*bend_present) (void *handle, bend_present_rr *rr);
3552
3553 typedef struct {
3554     char *setname;             /* set name */
3555     int start;
3556     int number;                /* record number */
3557     Odr_oid *format;           /* format, transfer syntax (OID) */
3558     Z_ReferenceId *referenceId;/* reference ID */
3559     Z_RecordComposition *comp; /* Formatting instructions */
3560     ODR stream;                /* encoding stream - memory source if required */
3561     ODR print;                 /* printing stream */
3562     bend_request request;
3563     bend_association association;
3564
3565     int hits;                  /* number of hits */
3566     int errcode;               /* 0==OK */
3567     char *errstring;           /* system error string or NULL */
3568 } bend_present_rr;
3569     </synopsis>
3570     <para>
3571      The <function>bend_present</function> handler is called when
3572      the server receives a Z39.50 Present Request.
3573      The <literal>setname</literal>,
3574      <literal>start</literal> and <literal>number</literal> is the
3575      name of the result set - start position - and number of records to
3576      be retrieved respectively. <literal>format</literal> and
3577      <literal>comp</literal> is the preferred transfer syntax and element
3578      specifications of the present request.
3579     </para>
3580     <para>
3581      Note that this is handler serves as a supplement for
3582      <function>bend_fetch</function> and need not to be defined in order to
3583      support search - and retrieve.
3584     </para>
3585    </sect2>
3586    <sect2 id="server.delete">
3587     <title>Delete</title>
3588     <para>
3589      For back-ends that supports delete of a result set only one handler
3590      must be defined.
3591     </para>
3592     <synopsis>
3593 int (*bend_delete)(void *handle, bend_delete_rr *rr);
3594
3595 typedef struct bend_delete_rr {
3596     int function;
3597     int num_setnames;
3598     char **setnames;
3599     Z_ReferenceId *referenceId;
3600     int delete_status;      /* status for the whole operation */
3601     int *statuses;          /* status each set - indexed as setnames */
3602     ODR stream;
3603     ODR print;
3604 } bend_delete_rr;
3605     </synopsis>
3606     <note>
3607      <para>
3608       The delete set function definition is rather primitive, mostly because
3609       we have had no practical need for it as of yet. If someone wants
3610       to provide a full delete service, we'd be happy to add the
3611       extra parameters that are required. Are there clients out there
3612       that will actually delete sets they no longer need?
3613      </para>
3614     </note>
3615    </sect2>
3616    <sect2 id="server.scan">
3617     <title>Scan</title>
3618     <para>
3619      For servers that wish to offer the scan service one handler
3620      must be defined.
3621     </para>
3622     <synopsis>
3623 int (*bend_scan)(void *handle, bend_scan_rr *rr);
3624
3625 typedef enum {
3626     BEND_SCAN_SUCCESS,  /* ok */
3627     BEND_SCAN_PARTIAL   /* not all entries could be found */
3628 } bend_scan_status;
3629
3630 typedef struct bend_scan_rr {
3631     int num_bases;      /* number of elements in databaselist */
3632     char **basenames;   /* databases to search */
3633     Odr_oid *attributeset;
3634     Z_ReferenceId *referenceId; /* reference ID */
3635     Z_AttributesPlusTerm *term;
3636     ODR stream;         /* encoding stream - memory source if required */
3637     ODR print;          /* printing stream */
3638
3639     int *step_size;     /* step size */
3640     int term_position;  /* desired index of term in result list/returned */
3641     int num_entries;    /* number of entries requested/returned */
3642
3643     /* scan term entries. The called handler does not have
3644        to allocate this. Size of entries is num_entries (see above) */
3645     struct scan_entry *entries;
3646     bend_scan_status status;
3647     int errcode;
3648     char *errstring;
3649     char *scanClause;   /* CQL scan clause */
3650     char *setname;      /* Scan in result set (NULL if omitted) */
3651 } bend_scan_rr;
3652     </synopsis>
3653    <para>
3654     This backend server handles both Z39.50 scan
3655     and SRU scan. In order for a handler to distinguish between SRU (CQL) scan
3656     Z39.50 Scan , it must check for a non-NULL value of
3657     <literal>scanClause</literal>.
3658    </para>
3659    <note>
3660     <para>
3661      if designed today, it would be a choice using a union or similar,
3662      but that would break binary compatibility with existing servers.
3663     </para>
3664     </note>
3665    </sect2>
3666   </sect1>
3667   <sect1 id="server.invocation">
3668    <title>Application Invocation</title>
3669    <para>
3670     The finished application has the following
3671     invocation syntax (by way of <function>statserv_main()</function>):
3672    </para>
3673    &gfs-synopsis;
3674    <para>
3675     The options are:
3676     &gfs-options;
3677    </para>
3678    <para>
3679     A listener specification consists of a transport mode followed by a
3680     colon (:) followed by a listener address. The transport mode is
3681     either <literal>tcp</literal>, <literal>unix:</literal> or
3682     <literal>ssl</literal>.
3683    </para>
3684    <para>
3685     For TCP and SSL, an address has the form
3686    </para>
3687    <synopsis>
3688     hostname | IP-number [: portnumber]
3689    </synopsis>
3690    <para>
3691     The port number defaults to 210 (standard Z39.50 port).
3692    </para>
3693    <para>
3694     For UNIX, the address is the filename of socket.
3695    </para>
3696    <para>
3697     For TCP/IP and SSL, the special hostnames <literal>@</literal>,
3698     maps to <literal>IN6ADDR_ANY_INIT</literal> with
3699     IPV4 binding as well (bindv6only=0),
3700     The special hostname <literal>@4</literal> binds to
3701     <literal>INADDR_ANY</literal> (IPV4 only listener).
3702     The special hostname <literal>@6</literal> binds to
3703     <literal>IN6ADDR_ANY_INIT</literal> with bindv6only=1 (IPV6 only listener).
3704    </para>
3705    <example id="server.example.running.unix">
3706     <title>Running the GFS on Unix</title>
3707     <para>
3708      Assuming the server application <replaceable>appname</replaceable> is
3709      started as root, the following will make it listen on port 210.
3710      The server will change identity to <literal>nobody</literal>
3711      and write its log to <filename>/var/log/app.log</filename>.
3712      <screen>
3713       application -l /var/log/app.log -u nobody tcp:@:210
3714      </screen>
3715     </para>
3716     <para>
3717      The server will accept Z39.50 requests and offer SRU service on port 210.
3718     </para>
3719    </example>
3720    <example id="server.example.apache.sru">
3721     <title>Setting up Apache as SRU Frontend</title>
3722     <para>
3723      If you use <ulink url="&url.apache;">Apache</ulink>
3724      as your public web server and want to offer HTTP port 80
3725      access to the YAZ server on 210, you can use the
3726      <ulink url="&url.apache.directive.proxypass;">
3727       <literal>ProxyPass</literal></ulink>
3728      directive.
3729      If you have virtual host
3730      <literal>srw.mydomain</literal> you can use the following directives
3731      in Apache's httpd.conf:
3732      <screen>
3733       &lt;VirtualHost *>
3734        ErrorLog /home/srw/logs/error_log
3735        TransferLog /home/srw/logs/access_log
3736        ProxyPass / http://srw.mydomain:210/
3737       &lt;/VirtualHost>
3738      </screen>
3739     </para>
3740     <para>
3741      The above for the Apache 1.3 series.
3742     </para>
3743    </example>
3744    <example id="server.example.local.access">
3745     <title>Running a server with local access only</title>
3746     <para>
3747      Servers that is only being accessed from the local host should listen
3748      on UNIX file socket rather than a Internet socket. To listen on
3749      <filename>/tmp/mysocket</filename> start the server as follows:
3750      <screen>
3751       application unix:/tmp/mysocket
3752      </screen>
3753     </para>
3754    </example>
3755   </sect1>
3756   <sect1 id="server.vhosts">
3757    <title>GFS Configuration and Virtual Hosts</title>
3758    &gfs-virtual;
3759   </sect1>
3760  </chapter>
3761  <chapter id="asn">
3762   <title>The Z39.50 ASN.1 Module</title>
3763   <sect1 id="asn.introduction">
3764    <title>Introduction</title>
3765    <para>
3766     The &asn; module provides you with a set of C struct definitions for the
3767     various PDUs of the Z39.50 protocol, as well as for the complex types
3768     appearing within the PDUs. For the primitive data types, the C
3769     representation often takes the form of an ordinary C language type,
3770     such as <literal>Odr_int</literal> which is equivalent to an integral
3771     C integer. For ASN.1 constructs that have no direct
3772     representation in C, such as general octet strings and bit strings,
3773     the &odr; module (see section <link linkend="odr">The ODR Module</link>)
3774     provides auxiliary definitions.
3775    </para>
3776    <para>
3777     The &asn; module is located in sub directory <filename>z39.50</filename>.
3778     There you'll find C files that implements encoders and decoders for the
3779     Z39.50 types. You'll also find the protocol definitions:
3780     <filename>z3950v3.asn</filename>, <filename>esupdate.asn</filename>,
3781     and others.
3782    </para>
3783   </sect1>
3784   <sect1 id="asn.preparing">
3785    <title>Preparing PDUs</title>
3786    <para>
3787     A structure representing a complex ASN.1 type doesn't in itself contain the
3788     members of that type. Instead, the structure contains
3789     <emphasis>pointers</emphasis> to the members of the type.
3790     This is necessary, in part, to allow a mechanism for specifying which
3791     of the optional structure (SEQUENCE) members are present, and which
3792     are not. It follows that you will need to somehow provide space for
3793     the individual members of the structure, and set the pointers to
3794     refer to the members.
3795    </para>
3796    <para>
3797     The conversion routines don't care how you allocate and maintain your
3798     C structures - they just follow the pointers that you provide.
3799     Depending on the complexity of your application, and your personal
3800     taste, there are at least three different approaches that you may take
3801     when you allocate the structures.
3802    </para>
3803    <para>
3804     You can use static or automatic local variables in the function that
3805     prepares the PDU. This is a simple approach, and it provides the most
3806     efficient form of memory management. While it works well for flat
3807     PDUs like the InitReqest, it will generally not be sufficient for say,
3808     the generation of an arbitrarily complex RPN query structure.
3809    </para>
3810    <para>
3811     You can individually create the structure and its members using the
3812     <function>malloc(2)</function> function. If you want to ensure that
3813     the data is freed when it is no longer needed, you will have to
3814     define a function that individually releases each member of a
3815     structure before freeing the structure itself.
3816    </para>
3817    <para>
3818     You can use the <function>odr_malloc()</function> function (see
3819     <xref linkend="odr.use"/> for details). When you use
3820     <function>odr_malloc()</function>, you can release all of the
3821     allocated data in a single operation, independent of any pointers and
3822     relations between the data. <function>odr_malloc()</function> is based on a
3823     &quot;nibble-memory&quot;
3824     scheme, in which large portions of memory are allocated, and then
3825     gradually handed out with each call to <function>odr_malloc()</function>.
3826     The next time you call <function>odr_reset()</function>, all of the
3827     memory allocated since the last call is recycled for future use (actually,
3828     it is placed on a free-list).
3829    </para>
3830    <para>
3831     You can combine all of the methods described here. This will often be
3832     the most practical approach. For instance, you might use
3833     <function>odr_malloc()</function> to allocate an entire structure and
3834     some of its elements, while you leave other elements pointing to global
3835     or per-session default variables.
3836    </para>
3837    <para>
3838     The &asn; module provides an important aid in creating new PDUs. For
3839     each of the PDU types (say, <function>Z_InitRequest</function>), a
3840     function is provided that allocates and initializes an instance of
3841     that PDU type for you. In the case of the InitRequest, the function is
3842     simply named <function>zget_InitRequest()</function>, and it sets up
3843     reasonable default value for all of the mandatory members. The optional
3844     members are generally initialized to null pointers. This last aspect
3845     is very important: it ensures that if the PDU definitions are
3846     extended after you finish your implementation (to accommodate
3847     new versions of the protocol, say), you won't get into trouble with
3848     uninitialized pointers in your structures. The functions use
3849     <function>odr_malloc()</function> to
3850     allocate the PDUs and its members, so you can free everything again with a
3851     single call to <function>odr_reset()</function>. We strongly recommend
3852     that you use the <literal>zget_*</literal>
3853     functions whenever you are preparing a PDU (in a C++ API, the
3854     <literal>zget_</literal>
3855     functions would probably be promoted to constructors for the
3856     individual types).
3857    </para>
3858    <para>
3859    The prototype for the individual PDU types generally look like this:
3860    </para>
3861    <synopsis>
3862     Z_&lt;type> *zget_&lt;type>(ODR o);
3863    </synopsis>
3864    <para>
3865     eg.:
3866    </para>
3867    <synopsis>
3868     Z_InitRequest *zget_InitRequest(ODR o);
3869    </synopsis>
3870    <para>
3871    The &odr; handle should generally be your encoding stream, but it
3872     needn't be.
3873    </para>
3874    <para>
3875     As well as the individual PDU functions, a function
3876     <function>zget_APDU()</function> is provided, which allocates
3877     a top-level Z-APDU of the type requested:
3878    </para>
3879    <synopsis>
3880     Z_APDU *zget_APDU(ODR o, int which);
3881    </synopsis>
3882    <para>
3883     The <varname>which</varname> parameter is (of course) the discriminator
3884     belonging to the <varname>Z_APDU</varname> <literal>CHOICE</literal> type.
3885     All of the interface described here is provided by the &asn; module, and
3886     you access it through the <filename>proto.h</filename> header file.
3887    </para>
3888   </sect1>
3889   <sect1 id="asn.external">
3890    <title>EXTERNAL Data</title>
3891    <para>
3892     In order to achieve extensibility and adaptability to different
3893     application domains, the new version of the protocol defines many
3894     structures outside of the main ASN.1 specification, referencing them
3895     through ASN.1 EXTERNAL constructs. To simplify the construction and
3896     access to the externally referenced data, the &asn; module defines a
3897     specialized version of the EXTERNAL construct, called
3898     <literal>Z_External</literal>.It is defined thus:
3899    </para>
3900    <screen>
3901 typedef struct Z_External
3902 {
3903     Odr_oid *direct_reference;
3904     int *indirect_reference;
3905     char *descriptor;
3906     enum
3907     {
3908         /* Generic types */
3909         Z_External_single = 0,
3910         Z_External_octet,
3911         Z_External_arbitrary,
3912
3913         /* Specific types */
3914         Z_External_SUTRS,
3915         Z_External_explainRecord,
3916         Z_External_resourceReport1,
3917         Z_External_resourceReport2
3918
3919     ...
3920
3921     } which;
3922     union
3923     {
3924         /* Generic types */
3925         Odr_any *single_ASN1_type;
3926         Odr_oct *octet_aligned;
3927         Odr_bitmask *arbitrary;
3928
3929         /* Specific types */
3930         Z_SUTRS *sutrs;
3931         Z_ExplainRecord *explainRecord;
3932         Z_ResourceReport1 *resourceReport1;
3933         Z_ResourceReport2 *resourceReport2;
3934
3935         ...
3936
3937     } u;
3938 } Z_External;
3939    </screen>
3940    <para>
3941     When decoding, the &asn; module will attempt to determine which
3942     syntax describes the data by looking at the reference fields
3943     (currently only the direct-reference). For ASN.1 structured data, you
3944     need only consult the <literal>which</literal> field to determine the
3945     type of data. You can the access  the data directly through the union.
3946     When constructing data for encoding, you set the union pointer to point
3947     to the data, and set the <literal>which</literal> field accordingly.
3948     Remember also to set the direct (or indirect) reference to the correct
3949     OID for the data type.
3950     For non-ASN.1 data such as MARC records, use the
3951     <literal>octet_aligned</literal> arm of the union.
3952    </para>
3953    <para>
3954     Some servers return ASN.1 structured data values (eg. database
3955     records) as BER-encoded records placed in the
3956     <literal>octet-aligned</literal> branch of the EXTERNAL CHOICE.
3957     The ASN-module will <emphasis>not</emphasis> automatically decode
3958     these records. To help you decode the records in the application, the
3959     function
3960    </para>
3961    <screen>
3962    Z_ext_typeent *z_ext_gettypebyref(const oid *oid);
3963    </screen>
3964    <para>
3965     Can be used to retrieve information about the known, external data
3966     types. The function return a pointer to a static area, or NULL, if no
3967     match for the given direct reference is found. The
3968     <literal>Z_ext_typeent</literal>
3969     is defined as:
3970    </para>
3971    <screen>
3972 typedef struct Z_ext_typeent
3973 {
3974     int oid[OID_SIZE]; /* the direct-reference OID. */
3975     int what;          /* discriminator value for the external CHOICE */
3976     Odr_fun fun;       /* decoder function */
3977 } Z_ext_typeent;
3978    </screen>
3979    <para>
3980     The <literal>what</literal> member contains the
3981     <literal>Z_External</literal> union discriminator value for the
3982     given type: For the SUTRS record syntax, the value would be
3983     <literal>Z_External_sutrs</literal>.
3984     The <literal>fun</literal> member contains a pointer to the
3985     function which encodes/decodes the given type. Again, for the SUTRS
3986     record syntax, the value of <literal>fun</literal> would be
3987     <literal>z_SUTRS</literal> (a function pointer).
3988    </para>
3989    <para>
3990     If you receive an EXTERNAL which contains an octet-string value that
3991     you suspect of being an ASN.1-structured data value, you can use
3992     <literal>z_ext_gettypebyref</literal> to look for the provided
3993     direct-reference.
3994     If the return value is different from NULL, you can use the provided
3995     function to decode the BER string (see <xref linkend="odr.use"/>
3996     ).
3997    </para>
3998    <para>
3999     If you want to <emphasis>send</emphasis> EXTERNALs containing
4000     ASN.1-structured values in the occtet-aligned branch of the CHOICE, this
4001     is possible too. However, on the encoding phase, it requires a somewhat
4002     involved juggling around of the various buffers involved.
4003    </para>
4004    <para>
4005     If you need to add new, externally defined data types, you must update
4006     the struct above, in the source file <filename>prt-ext.h</filename>, as
4007     well as the encoder/decoder in the file <filename>prt-ext.c</filename>.
4008     When changing the latter, remember to update both the
4009     <literal>arm</literal> arrary and the list
4010     <literal>type_table</literal>, which drives the CHOICE biasing that
4011     is necessary to tell the different, structured types apart
4012     on decoding.
4013    </para>
4014    <note>
4015     <para>
4016      Eventually, the EXTERNAL processing will most likely
4017      automatically insert the correct OIDs or indirect-refs. First,
4018      however, we need to determine how application-context management
4019      (specifically the presentation-context-list) should fit into the
4020      various modules.
4021     </para>
4022    </note>
4023   </sect1>
4024   <sect1 id="asn.pdu">
4025    <title>PDU Contents Table</title>
4026    <para>
4027     We include, for reference, a listing of the fields of each top-level
4028     PDU, as well as their default settings.
4029    </para>
4030    <table frame="top" id="asn.default.initialize.request">
4031     <title>Default settings for PDU Initialize Request</title>
4032     <tgroup cols="3">
4033      <colspec colwidth="7*" colname="field"></colspec>
4034      <colspec colwidth="5*" colname="type"></colspec>
4035      <colspec colwidth="7*" colname="value"></colspec>
4036     <thead>
4037      <row>
4038       <entry>Field</entry>
4039       <entry>Type</entry>
4040       <entry>Default Value</entry>
4041      </row>
4042     </thead>
4043     <tbody>
4044      <row><entry>
4045       referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
4046      </entry></row>
4047      <row><entry>
4048       protocolVersion</entry><entry>Odr_bitmask</entry><entry>Empty bitmask
4049      </entry></row>
4050      <row><entry>
4051       options</entry><entry>Odr_bitmask</entry><entry>Empty bitmask
4052      </entry></row>
4053      <row><entry>
4054       preferredMessageSize</entry><entry>Odr_int</entry><entry>30*1024
4055      </entry></row>
4056      <row><entry>
4057       maximumRecordSize</entry><entry>Odr_int</entry><entry>30*1024
4058      </entry></row>
4059      <row><entry>
4060       idAuthentication</entry><entry>Z_IdAuthentication</entry><entry>NULL
4061      </entry></row>
4062      <row><entry>
4063       implementationId</entry><entry>char*</entry><entry>"81"
4064      </entry></row>
4065      <row><entry>
4066       implementationName</entry><entry>char*</entry><entry>"YAZ"
4067      </entry></row>
4068      <row><entry>
4069       implementationVersion</entry><entry>char*</entry><entry>YAZ_VERSION
4070      </entry></row>
4071      <row><entry>
4072       userInformationField</entry><entry>Z_UserInformation</entry><entry>NULL
4073      </entry></row>
4074      <row><entry>
4075       otherInfo</entry><entry>Z_OtherInformation</entry><entry>NULL
4076      </entry></row>
4077     </tbody>
4078     </tgroup>
4079    </table>
4080    <table frame="top" id="asn.default.initialize.response">
4081     <title>Default settings for PDU Initialize Response</title>
4082     <tgroup cols="3">
4083      <colspec colwidth="7*" colname="field"></colspec>
4084      <colspec colwidth="5*" colname="type"></colspec>
4085      <colspec colwidth="7*" colname="value"></colspec>
4086      <thead>
4087       <row>
4088        <entry>Field</entry>
4089        <entry>Type</entry>
4090        <entry>Default Value</entry>
4091       </row>
4092      </thead>
4093      <tbody>
4094       <row><entry>
4095        referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
4096       </entry></row>
4097       <row><entry>
4098        protocolVersion</entry><entry>Odr_bitmask</entry><entry>Empty bitmask
4099       </entry></row>
4100       <row><entry>
4101        options</entry><entry>Odr_bitmask</entry><entry>Empty bitmask
4102       </entry></row>
4103       <row><entry>
4104        preferredMessageSize</entry><entry>Odr_int</entry><entry>30*1024
4105       </entry></row>
4106       <row><entry>
4107        maximumRecordSize</entry><entry>Odr_int</entry><entry>30*1024
4108       </entry></row>
4109       <row><entry>
4110        result</entry><entry>Odr_bool</entry><entry>TRUE
4111       </entry></row>
4112       <row><entry>
4113        implementationId</entry><entry>char*</entry><entry>"id)"
4114       </entry></row>
4115       <row><entry>
4116        implementationName</entry><entry>char*</entry><entry>"YAZ"
4117       </entry></row>
4118       <row><entry>
4119        implementationVersion</entry><entry>char*</entry><entry>YAZ_VERSION
4120       </entry></row>
4121       <row><entry>
4122        userInformationField</entry><entry>Z_UserInformation</entry><entry>NULL
4123       </entry></row>
4124       <row><entry>
4125        otherInfo</entry><entry>Z_OtherInformation</entry><entry>NULL
4126       </entry></row>
4127      </tbody>
4128     </tgroup>
4129    </table>
4130    <table frame="top" id="asn.default.search.request">
4131     <title>Default settings for PDU Search Request</title>
4132     <tgroup cols="3">
4133      <colspec colwidth="7*" colname="field"></colspec>
4134      <colspec colwidth="5*" colname="type"></colspec>
4135      <colspec colwidth="7*" colname="value"></colspec>
4136      <thead>
4137       <row>
4138        <entry>Field</entry>
4139        <entry>Type</entry>
4140        <entry>Default Value</entry>
4141       </row>
4142      </thead>
4143      <tbody>
4144       <row><entry>
4145         referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
4146        </entry></row>
4147       <row><entry>
4148         smallSetUpperBound</entry><entry>Odr_int</entry><entry>0
4149        </entry></row>
4150       <row><entry>
4151         largeSetLowerBound</entry><entry>Odr_int</entry><entry>1
4152        </entry></row>
4153       <row><entry>
4154         mediumSetPresentNumber</entry><entry>Odr_int</entry><entry>0
4155        </entry></row>
4156       <row><entry>
4157         replaceIndicator</entry><entry>Odr_bool</entry><entry>TRUE
4158        </entry></row>
4159       <row><entry>
4160         resultSetName</entry><entry>char *</entry><entry>"default"
4161        </entry></row>
4162       <row><entry>
4163         num_databaseNames</entry><entry>Odr_int</entry><entry>0
4164        </entry></row>
4165       <row><entry>
4166         databaseNames</entry><entry>char **</entry><entry>NULL
4167        </entry></row>
4168       <row><entry>
4169         smallSetElementSetNames</entry><entry>Z_ElementSetNames
4170        </entry><entry>NULL
4171        </entry></row>
4172       <row><entry>
4173         mediumSetElementSetNames</entry><entry>Z_ElementSetNames
4174        </entry><entry>NULL
4175        </entry></row>
4176       <row><entry>
4177         preferredRecordSyntax</entry><entry>Odr_oid</entry><entry>NULL
4178        </entry></row>
4179       <row><entry>
4180         query</entry><entry>Z_Query</entry><entry>NULL
4181        </entry></row>
4182       <row><entry>
4183         additionalSearchInfo</entry><entry>Z_OtherInformation
4184        </entry><entry>NULL
4185        </entry></row>
4186       <row><entry>
4187         otherInfo</entry><entry>Z_OtherInformation</entry><entry>NULL
4188        </entry></row>
4189      </tbody>
4190     </tgroup>
4191    </table>
4192    <table frame="top" id="asn.default.search.response">
4193     <title>Default settings for PDU Search Response</title>
4194     <tgroup cols="3">
4195      <colspec colwidth="7*" colname="field"></colspec>
4196      <colspec colwidth="5*" colname="type"></colspec>
4197      <colspec colwidth="7*" colname="value"></colspec>
4198      <thead>
4199       <row>
4200        <entry>Field</entry>
4201        <entry>Type</entry>
4202        <entry>Default Value</entry>
4203       </row>
4204      </thead>
4205      <tbody>
4206       <row><entry>
4207        referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
4208       </entry></row>
4209       <row><entry>
4210        resultCount</entry><entry>Odr_int</entry><entry>0
4211       </entry></row>
4212       <row><entry>
4213        numberOfRecordsReturned</entry><entry>Odr_int</entry><entry>0
4214       </entry></row>
4215       <row><entry>
4216        nextResultSetPosition</entry><entry>Odr_int</entry><entry>0
4217       </entry></row>
4218       <row><entry>
4219        searchStatus</entry><entry>Odr_bool</entry><entry>TRUE
4220       </entry></row>
4221       <row><entry>
4222        resultSetStatus</entry><entry>Odr_int</entry><entry>NULL
4223       </entry></row>
4224       <row><entry>
4225        presentStatus</entry><entry>Odr_int</entry><entry>NULL
4226       </entry></row>
4227       <row><entry>
4228        records</entry><entry>Z_Records</entry><entry>NULL
4229       </entry></row>
4230       <row><entry>
4231        additionalSearchInfo</entry>
4232        <entry>Z_OtherInformation</entry><entry>NULL
4233       </entry></row>
4234       <row><entry>
4235        otherInfo</entry><entry>Z_OtherInformation</entry><entry>NULL
4236       </entry></row>
4237      </tbody>
4238     </tgroup>
4239    </table>
4240    <table frame="top" id="asn.default.present.request">
4241     <title>Default settings for PDU Present Request</title>
4242     <tgroup cols="3">
4243      <colspec colwidth="7*" colname="field"></colspec>
4244      <colspec colwidth="5*" colname="type"></colspec>
4245      <colspec colwidth="7*" colname="value"></colspec>
4246      <thead>
4247       <row>
4248        <entry>Field</entry>
4249        <entry>Type</entry>
4250        <entry>Default Value</entry>
4251       </row>
4252      </thead>
4253      <tbody>
4254       <row><entry>
4255         referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
4256        </entry></row>
4257       <row><entry>
4258         resultSetId</entry><entry>char*</entry><entry>"default"
4259        </entry></row>
4260       <row><entry>
4261         resultSetStartPoint</entry><entry>Odr_int</entry><entry>1
4262        </entry></row>
4263       <row><entry>
4264         numberOfRecordsRequested</entry><entry>Odr_int</entry><entry>10
4265        </entry></row>
4266       <row><entry>
4267         num_ranges</entry><entry>Odr_int</entry><entry>0
4268        </entry></row>
4269       <row><entry>
4270         additionalRanges</entry><entry>Z_Range</entry><entry>NULL
4271        </entry></row>
4272       <row><entry>
4273         recordComposition</entry><entry>Z_RecordComposition</entry><entry>NULL
4274        </entry></row>
4275       <row><entry>
4276         preferredRecordSyntax</entry><entry>Odr_oid</entry><entry>NULL
4277        </entry></row>
4278       <row><entry>
4279         maxSegmentCount</entry><entry>Odr_int</entry><entry>NULL
4280        </entry></row>
4281       <row><entry>
4282         maxRecordSize</entry><entry>Odr_int</entry><entry>NULL
4283        </entry></row>
4284       <row><entry>
4285         maxSegmentSize</entry><entry>Odr_int</entry><entry>NULL
4286        </entry></row>
4287       <row><entry>
4288         otherInfo</entry><entry>Z_OtherInformation</entry><entry>NULL
4289        </entry></row>
4290      </tbody>
4291     </tgroup>
4292    </table>
4293    <table frame="top" id="asn.default.present.response">
4294     <title>Default settings for PDU Present Response</title>
4295     <tgroup cols="3">
4296      <colspec colwidth="7*" colname="field"></colspec>
4297      <colspec colwidth="5*" colname="type"></colspec>
4298      <colspec colwidth="7*" colname="value"></colspec>
4299      <thead>
4300       <row>
4301        <entry>Field</entry>
4302        <entry>Type</entry>
4303        <entry>Default Value</entry>
4304       </row>
4305      </thead>
4306      <tbody>
4307       <row><entry>
4308         referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
4309        </entry></row>
4310       <row><entry>
4311         numberOfRecordsReturned</entry><entry>Odr_int</entry><entry>0
4312        </entry></row>
4313       <row><entry>
4314         nextResultSetPosition</entry><entry>Odr_int</entry><entry>0
4315        </entry></row>
4316       <row><entry>
4317         presentStatus</entry><entry>Odr_int</entry><entry>Z_PresentStatus_success
4318        </entry></row>
4319       <row><entry>
4320         records</entry><entry>Z_Records</entry><entry>NULL
4321        </entry></row>
4322       <row><entry>
4323         otherInfo</entry><entry>Z_OtherInformation</entry><entry>NULL
4324        </entry></row>
4325      </tbody>
4326     </tgroup>
4327    </table>
4328    <table frame="top" id="asn.default.delete.result.set.request">
4329     <title>Default settings for Delete Result Set Request</title>
4330     <tgroup cols="3">
4331      <colspec colwidth="7*" colname="field"></colspec>
4332      <colspec colwidth="5*" colname="type"></colspec>
4333      <colspec colwidth="7*" colname="value"></colspec>
4334      <thead>
4335       <row>
4336        <entry>Field</entry>
4337        <entry>Type</entry>
4338        <entry>Default Value</entry>
4339       </row>
4340      </thead>
4341      <tbody>
4342       <row><entry>referenceId
4343        </entry><entry>Z_ReferenceId</entry><entry>NULL
4344        </entry></row>
4345       <row><entry>
4346         deleteFunction</entry><entry>Odr_int</entry><entry>Z_DeleteResultSetRequest_list
4347        </entry></row>
4348       <row><entry>
4349         num_ids</entry><entry>Odr_int</entry><entry>0
4350        </entry></row>
4351       <row><entry>
4352         resultSetList</entry><entry>char**</entry><entry>NULL
4353        </entry></row>
4354       <row><entry>
4355         otherInfo</entry><entry>Z_OtherInformation</entry><entry>NULL
4356        </entry></row>
4357      </tbody>
4358     </tgroup>
4359    </table>
4360    <table frame="top" id="asn.default.delete.result.set.response">
4361     <title>Default settings for Delete Result Set Response</title>
4362     <tgroup cols="3">
4363      <colspec colwidth="7*" colname="field"></colspec>
4364      <colspec colwidth="5*" colname="type"></colspec>
4365      <colspec colwidth="7*" colname="value"></colspec>
4366      <thead>
4367       <row>
4368        <entry>Field</entry>
4369        <entry>Type</entry>
4370        <entry>Default Value</entry>
4371       </row>
4372      </thead>
4373      <tbody>
4374       <row><entry>
4375         referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
4376        </entry></row>
4377       <row><entry>
4378         deleteOperationStatus</entry><entry>Odr_int</entry>
4379        <entry>Z_DeleteStatus_success</entry></row>
4380       <row><entry>
4381         num_statuses</entry><entry>Odr_int</entry><entry>0
4382        </entry></row>
4383       <row><entry>
4384         deleteListStatuses</entry><entry>Z_ListStatus**</entry><entry>NULL
4385        </entry></row>
4386       <row><entry>
4387         numberNotDeleted</entry><entry>Odr_int</entry><entry>NULL
4388        </entry></row>
4389       <row><entry>
4390         num_bulkStatuses</entry><entry>Odr_int</entry><entry>0
4391        </entry></row>
4392       <row><entry>
4393         bulkStatuses</entry><entry>Z_ListStatus</entry><entry>NUL
4394         L</entry></row>
4395       <row><entry>
4396         deleteMessage</entry><entry>char*</entry><entry>NULL
4397        </entry></row>
4398       <row><entry>
4399         otherInfo</entry><entry>Z_OtherInformation</entry><entry>NULL
4400        </entry></row>
4401      </tbody>
4402     </tgroup>
4403    </table>
4404    <table frame="top" id="asn.default.scan.request">
4405     <title>Default settings for Scan Request</title>
4406     <tgroup cols="3">
4407      <colspec colwidth="7*" colname="field"></colspec>
4408      <colspec colwidth="5*" colname="type"></colspec>
4409      <colspec colwidth="7*" colname="value"></colspec>
4410      <thead>
4411       <row>
4412        <entry>Field</entry>
4413        <entry>Type</entry>
4414        <entry>Default Value</entry>
4415       </row>
4416      </thead>
4417      <tbody>
4418       <row><entry>
4419         referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
4420        </entry></row>
4421       <row><entry>
4422         num_databaseNames</entry><entry>Odr_int</entry><entry>0
4423        </entry></row>
4424       <row><entry>
4425         databaseNames</entry><entry>char**</entry><entry>NULL
4426        </entry></row>
4427       <row><entry>
4428         attributeSet</entry><entry>Odr_oid</entry><entry>NULL
4429        </entry></row>
4430       <row><entry>
4431         termListAndStartPoint</entry><entry>Z_AttributesPlus...
4432        </entry><entry>NULL</entry></row>
4433       <row><entry>
4434         stepSize</entry><entry>Odr_int</entry><entry>NULL
4435        </entry></row>
4436       <row><entry>
4437         numberOfTermsRequested</entry><entry>Odr_int</entry><entry>20
4438        </entry></row>
4439       <row><entry>
4440         preferredPositionInResponse</entry><entry>Odr_int</entry><entry>NULL
4441        </entry></row>
4442       <row><entry>
4443         otherInfo</entry><entry>Z_OtherInformation</entry><entry>NULL
4444        </entry></row>
4445      </tbody>
4446     </tgroup>
4447    </table>
4448    <table frame="top" id="asn.default.scan.response">
4449     <title>Default settings for Scan Response</title>
4450     <tgroup cols="3">
4451      <colspec colwidth="7*" colname="field"></colspec>
4452      <colspec colwidth="5*" colname="type"></colspec>
4453      <colspec colwidth="7*" colname="value"></colspec>
4454      <thead>
4455       <row>
4456        <entry>Field</entry>
4457        <entry>Type</entry>
4458        <entry>Default Value</entry>
4459       </row>
4460      </thead>
4461      <tbody>
4462       <row><entry>
4463        referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
4464       </entry></row>
4465       <row><entry>
4466        stepSize</entry><entry>Odr_int</entry><entry>NULL
4467       </entry></row>
4468       <row><entry>
4469        scanStatus</entry><entry>Odr_int</entry><entry>Z_Scan_success
4470       </entry></row>
4471       <row><entry>
4472        numberOfEntriesReturned</entry><entry>Odr_int</entry><entry>0
4473       </entry></row>
4474       <row><entry>
4475        positionOfTerm</entry><entry>Odr_int</entry><entry>NULL
4476       </entry></row>
4477       <row><entry>
4478        entries</entry><entry>Z_ListEntris</entry><entry>NULL
4479       </entry></row>
4480       <row><entry>
4481        attributeSet</entry><entry>Odr_oid</entry><entry>NULL
4482       </entry></row>
4483       <row><entry>
4484        otherInfo</entry><entry>Z_OtherInformation</entry><entry>NULL
4485       </entry></row>
4486      </tbody>
4487     </tgroup>
4488    </table>
4489    <table frame="top" id="asn.default.trigger.resource.control.request">
4490     <title>Default settings for Trigger Resource Control Request</title>
4491     <tgroup cols="3">
4492      <colspec colwidth="7*" colname="field"></colspec>
4493      <colspec colwidth="5*" colname="type"></colspec>
4494      <colspec colwidth="7*" colname="value"></colspec>
4495      <thead>
4496       <row>
4497        <entry>Field</entry>
4498        <entry>Type</entry>
4499        <entry>Default Value</entry>
4500       </row>
4501      </thead>
4502      <tbody>
4503       <row><entry>
4504         referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
4505        </entry></row>
4506       <row><entry>
4507         requestedAction</entry><entry>Odr_int</entry><entry>
4508         Z_TriggerResourceCtrl_resou..
4509        </entry></row>
4510       <row><entry>
4511         prefResourceReportFormat</entry><entry>Odr_oid</entry><entry>NULL
4512        </entry></row>
4513       <row><entry>
4514         resultSetWanted</entry><entry>Odr_bool</entry><entry>NULL
4515        </entry></row>
4516       <row><entry>
4517         otherInfo</entry><entry>Z_OtherInformation</entry><entry>NULL
4518        </entry></row>
4519      </tbody>
4520     </tgroup>
4521    </table>
4522    <table frame="top" id="asn.default.resource.control.request">
4523     <title>Default settings for Resource Control Request</title>
4524     <tgroup cols="3">
4525      <colspec colwidth="7*" colname="field"></colspec>
4526      <colspec colwidth="5*" colname="type"></colspec>
4527      <colspec colwidth="7*" colname="value"></colspec>
4528      <thead>
4529       <row>
4530        <entry>Field</entry>
4531        <entry>Type</entry>
4532        <entry>Default Value</entry>
4533       </row>
4534      </thead>
4535      <tbody>
4536       <row><entry>
4537         referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
4538        </entry></row>
4539       <row><entry>
4540         suspendedFlag</entry><entry>Odr_bool</entry><entry>NULL
4541        </entry></row>
4542       <row><entry>
4543         resourceReport</entry><entry>Z_External</entry><entry>NULL
4544        </entry></row>
4545       <row><entry>
4546         partialResultsAvailable</entry><entry>Odr_int</entry><entry>NULL
4547        </entry></row>
4548       <row><entry>
4549         responseRequired</entry><entry>Odr_bool</entry><entry>FALSE
4550        </entry></row>
4551       <row><entry>
4552         triggeredRequestFlag</entry><entry>Odr_bool</entry><entry>NULL
4553        </entry></row>
4554       <row><entry>
4555         otherInfo</entry><entry>Z_OtherInformation</entry><entry>NULL
4556        </entry></row>
4557      </tbody>
4558     </tgroup>
4559    </table>
4560    <table frame="top" id="asn.default.resource.control.response">
4561     <title>Default settings for Resource Control Response</title>
4562     <tgroup cols="3">
4563      <colspec colwidth="7*" colname="field"></colspec>
4564      <colspec colwidth="5*" colname="type"></colspec>
4565      <colspec colwidth="7*" colname="value"></colspec>
4566      <thead>
4567       <row>
4568        <entry>Field</entry>
4569        <entry>Type</entry>
4570        <entry>Default Value</entry>
4571       </row>
4572      </thead>
4573      <tbody>
4574       <row><entry>
4575         referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
4576        </entry></row>
4577       <row><entry>
4578         continueFlag</entry><entry>bool_t</entry><entry>TRUE
4579        </entry></row>
4580       <row><entry>
4581         resultSetWanted</entry><entry>bool_t</entry><entry>NULL
4582        </entry></row>
4583       <row><entry>
4584         otherInfo</entry><entry>Z_OtherInformation</entry><entry>NULL
4585        </entry></row>
4586      </tbody>
4587     </tgroup>
4588    </table>
4589    <table frame="top" id="asn.default.access.control.request">
4590     <title>Default settings for Access Control Request</title>
4591     <tgroup cols="3">
4592      <colspec colwidth="7*" colname="field"></colspec>
4593      <colspec colwidth="5*" colname="type"></colspec>
4594      <colspec colwidth="7*" colname="value"></colspec>
4595      <thead>
4596       <row>
4597        <entry>Field</entry>
4598        <entry>Type</entry>
4599        <entry>Default Value</entry>
4600       </row>
4601      </thead>
4602      <tbody>
4603       <row><entry>
4604         referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
4605        </entry></row>
4606       <row><entry>
4607         which</entry><entry>enum</entry><entry>Z_AccessRequest_simpleForm;
4608        </entry></row>
4609       <row><entry>
4610         u</entry><entry>union</entry><entry>NULL
4611        </entry></row>
4612       <row><entry>
4613         otherInfo</entry><entry>Z_OtherInformation</entry><entry>NULL
4614        </entry></row>
4615      </tbody>
4616     </tgroup>
4617    </table>
4618    <table frame="top" id="asn.default.access.control.response">
4619     <title>Default settings for Access Control Response</title>
4620     <tgroup cols="3">
4621      <colspec colwidth="7*" colname="field"></colspec>
4622      <colspec colwidth="5*" colname="type"></colspec>
4623      <colspec colwidth="7*" colname="value"></colspec>
4624      <thead>
4625       <row>
4626        <entry>Field</entry>
4627        <entry>Type</entry>
4628        <entry>Default Value</entry>
4629       </row>
4630      </thead>
4631      <tbody>
4632       <row><entry>
4633         referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
4634        </entry></row>
4635       <row><entry>
4636         which</entry><entry>enum</entry><entry>Z_AccessResponse_simpleForm
4637        </entry></row>
4638       <row><entry>
4639         u</entry><entry>union</entry><entry>NULL
4640        </entry></row>
4641       <row><entry>
4642         diagnostic</entry><entry>Z_DiagRec</entry><entry>NULL
4643        </entry></row>
4644       <row><entry>
4645         otherInfo</entry><entry>Z_OtherInformation</entry><entry>NULL
4646        </entry></row>
4647      </tbody>
4648     </tgroup>
4649    </table>
4650    <table frame="top" id="asn.default.segment">
4651     <title>Default settings for Segment</title>
4652     <tgroup cols="3">
4653      <colspec colwidth="7*" colname="field"></colspec>
4654      <colspec colwidth="5*" colname="type"></colspec>
4655      <colspec colwidth="7*" colname="value"></colspec>
4656      <thead>
4657       <row>
4658        <entry>Field</entry>
4659        <entry>Type</entry>
4660        <entry>Default Value</entry>
4661       </row>
4662      </thead>
4663      <tbody>
4664       <row><entry>
4665         referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
4666        </entry></row>
4667       <row><entry>
4668         numberOfRecordsReturned</entry><entry>Odr_int</entry><entry>value=0
4669        </entry></row>
4670       <row><entry>
4671         num_segmentRecords</entry><entry>Odr_int</entry><entry>0
4672        </entry></row>
4673       <row><entry>
4674         segmentRecords</entry><entry>Z_NamePlusRecord</entry><entry>NULL
4675        </entry></row>
4676       <row><entry>otherInfo</entry><entry>Z_OtherInformation</entry><entry>NULL
4677        </entry></row>
4678      </tbody>
4679     </tgroup>
4680    </table>
4681    <table frame="top" id="asn.default.close">
4682     <title>Default settings for Close</title>
4683     <tgroup cols="3">
4684      <colspec colwidth="7*" colname="field"></colspec>
4685      <colspec colwidth="5*" colname="type"></colspec>
4686      <colspec colwidth="7*" colname="value"></colspec>
4687      <thead>
4688       <row>
4689        <entry>Field</entry>
4690        <entry>Type</entry>
4691        <entry>Default Value</entry>
4692       </row>
4693      </thead>
4694      <tbody>
4695       <row><entry>
4696         referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
4697        </entry></row>
4698       <row><entry>
4699         closeReason</entry><entry>Odr_int</entry><entry>Z_Close_finished
4700        </entry></row>
4701       <row><entry>
4702         diagnosticInformation</entry><entry>char*</entry><entry>NULL
4703        </entry></row>
4704       <row><entry>
4705         resourceReportFormat</entry><entry>Odr_oid</entry><entry>NULL
4706        </entry></row>
4707       <row><entry>
4708         resourceFormat</entry><entry>Z_External</entry><entry>NULL
4709        </entry></row>
4710       <row><entry>
4711         otherInfo</entry><entry>Z_OtherInformation</entry><entry>NULL
4712        </entry></row>
4713      </tbody>
4714     </tgroup>
4715    </table>
4716   </sect1>
4717  </chapter>
4718  <chapter id="soap">
4719   <title>SOAP and SRU</title>
4720   <sect1 id="soap.introduction">
4721    <title>Introduction</title>
4722    <para>
4723     &yaz; uses a very simple implementation of
4724     <ulink url="&url.soap;">SOAP</ulink> that only,
4725     currenly, supports what is sufficient to offer SRU SOAP functionality.
4726     The implementation uses the
4727     <ulink url="&url.libxml2.api.tree;">tree API</ulink> of
4728     libxml2 to encode and decode SOAP packages.
4729    </para>
4730    <para>
4731     Like the Z39.50 ASN.1 module, the &yaz; SRU implementation uses
4732     simple C structs to represent SOAP packages as well as
4733     HTTP packages.
4734    </para>
4735   </sect1>
4736   <sect1 id="soap.http">
4737    <title>HTTP</title>
4738    <para>
4739     &yaz; only offers HTTP as transport carrier for SOAP, but it is
4740     relatively easy to change that.
4741    </para>
4742    <para>
4743     The following definition of <literal>Z_GDU</literal> (Generic Data
4744     Unit) allows for both HTTP and Z39.50 in one packet.
4745    </para>
4746    <synopsis>
4747 #include &lt;yaz/zgdu.h&gt;
4748
4749 #define Z_GDU_Z3950         1
4750 #define Z_GDU_HTTP_Request  2
4751 #define Z_GDU_HTTP_Response 3
4752 typedef struct {
4753   int which;
4754   union {
4755     Z_APDU *z3950;
4756     Z_HTTP_Request *HTTP_Request;
4757     Z_HTTP_Response *HTTP_Response;
4758   } u;
4759 } Z_GDU ;
4760    </synopsis>
4761    <para>
4762     The corresponding Z_GDU encoder/decoder is <function>z_GDU</function>.
4763     The <literal>z3950</literal> is any of the known BER encoded Z39.50
4764     APDUs.
4765     <literal>HTTP_Request</literal> and <literal>HTTP_Response</literal>
4766     is the HTTP Request and Response respectively.
4767    </para>
4768   </sect1>
4769   <sect1 id="soap.xml">
4770    <title>SOAP Packages</title>
4771    <para>
4772     Every SOAP package in &yaz; is represented as follows:
4773     <synopsis>
4774 #include &lt;yaz/soap.h&gt;
4775
4776 typedef struct {
4777     char *fault_code;
4778     char *fault_string;
4779     char *details;
4780 } Z_SOAP_Fault;
4781
4782 typedef struct {
4783     int no;
4784     char *ns;
4785     void *p;
4786 } Z_SOAP_Generic;
4787
4788 #define Z_SOAP_fault 1
4789 #define Z_SOAP_generic 2
4790 #define Z_SOAP_error 3
4791 typedef struct {
4792     int which;
4793     union {
4794         Z_SOAP_Fault   *fault;
4795         Z_SOAP_Generic *generic;
4796         Z_SOAP_Fault   *soap_error;
4797     } u;
4798     const char *ns;
4799 } Z_SOAP;
4800     </synopsis>
4801    </para>
4802    <para>
4803     The <literal>fault</literal> and <literal>soap_error</literal>
4804     arms represent both a SOAP fault - struct
4805     <literal>Z_SOAP_Fault</literal>. Any other generic
4806     (valid) package is represented by <literal>Z_SOAP_Generic</literal>.
4807    </para>
4808    <para>
4809     The <literal>ns</literal> as part of <literal>Z_SOAP</literal>
4810     is the namespace for SOAP itself and reflects the SOAP
4811     version. For version 1.1 it is
4812     <literal>http://schemas.xmlsoap.org/soap/envelope/</literal>,
4813     for version 1.2 it is
4814     <literal>http://www.w3.org/2001/06/soap-envelope</literal>.
4815    </para>
4816    <synopsis>
4817 int z_soap_codec(ODR o, Z_SOAP **pp,
4818                  char **content_buf, int *content_len,
4819                  Z_SOAP_Handler *handlers);
4820    </synopsis>
4821    <para>
4822     The <literal>content_buf</literal> and <literal>content_len</literal>
4823     is XML buffer and length of buffer respectively.
4824    </para>
4825    <para>
4826     The <literal>handlers</literal> is a list of SOAP codec
4827     handlers - one handler for each service namespace. For SRU SOAP, the
4828     namespace would be <literal>http://www.loc.gov/zing/srw/v1.0/</literal>.
4829    </para>
4830    <para>
4831     When decoding, the <function>z_soap_codec</function>
4832     inspects the XML content
4833     and tries to match one of the services namespaces of the
4834     supplied handlers. If there is a match a handler function
4835     is invoked which decodes that particular SOAP package.
4836     If successful, the returned <literal>Z_SOAP</literal> package will be
4837     of type <literal>Z_SOAP_Generic</literal>.
4838     Member <literal>no</literal> is
4839     set the offset of handler that matched; <literal>ns</literal>
4840     is set to namespace of matching handler; the void pointer
4841     <literal>p</literal> is set to the C data structure assocatiated
4842     with the handler.
4843    </para>
4844    <para>
4845     When a NULL namespace is met (member <literal>ns</literal> bwlow),
4846     that specifies end-of-list.
4847    </para>
4848    <para>
4849     Each handler is defined as follows:
4850     <synopsis>
4851 typedef struct {
4852     char *ns;
4853     void *client_data;
4854     Z_SOAP_fun f;
4855 } Z_SOAP_Handler;
4856     </synopsis>
4857     The <literal>ns</literal> is namespace of service associated with
4858     handler <literal>f</literal>. <literal>client_data</literal>
4859     is user-defined data which is passed to handler.
4860    </para>
4861    <para>
4862     The prototype for a SOAP service handler is:
4863     <synopsis>
4864 int handler(ODR o, void * ptr, void **handler_data,
4865             void *client_data, const char *ns);
4866     </synopsis>
4867     The <parameter>o</parameter> specifies the mode (decode/encode)
4868     as usual. The second argument, <parameter>ptr</parameter>,
4869     is a libxml2 tree node pointer (<literal>xmlNodePtr</literal>)
4870     and is a pointer to the <literal>Body</literal> element
4871     of the SOAP package. The <parameter>handler_data</parameter>
4872     is an opaque pointer to a C definitions associated with the
4873     SOAP service. <parameter>client_data</parameter> is the pointer
4874     which was set as part of the <literal>Z_SOAP_handler</literal>.
4875     Finally, <parameter>ns</parameter> the service namespace.
4876    </para>
4877   </sect1>
4878   <sect1 id="soap.srw">
4879    <title>SRU</title>
4880    <para>
4881     SRU SOAP is just one implementation of a SOAP handler as described
4882     in the previous section.
4883     The encoder/decoder handler for SRU is defined as
4884     follows:
4885     <synopsis>
4886 #include &lt;yaz/srw.h&gt;
4887
4888 int yaz_srw_codec(ODR o, void * pptr,
4889                   Z_SRW_GDU **handler_data,
4890                   void *client_data, const char *ns);
4891     </synopsis>
4892     Here, <literal>Z_SRW_GDU</literal> is either
4893     searchRetrieveRequest or a searchRetrieveResponse.
4894    </para>
4895    <note>
4896     <para>
4897      The xQuery and xSortKeys are not handled yet by
4898      the SRW implementation of &yaz;. Explain is also missing.
4899      Future versions of &yaz; will include these features.
4900     </para>
4901    </note>
4902    <para>
4903     The definition of searchRetrieveRequest is:
4904     <synopsis>
4905 typedef struct {
4906
4907 #define Z_SRW_query_type_cql  1
4908 #define Z_SRW_query_type_xcql 2
4909 #define Z_SRW_query_type_pqf  3
4910     int query_type;
4911     union {
4912         char *cql;
4913         char *xcql;
4914         char *pqf;
4915     } query;
4916
4917 #define Z_SRW_sort_type_none 1
4918 #define Z_SRW_sort_type_sort 2
4919 #define Z_SRW_sort_type_xSort 3
4920     int sort_type;
4921     union {
4922         char *none;
4923         char *sortKeys;
4924         char *xSortKeys;
4925     } sort;
4926     int  *startRecord;
4927     int  *maximumRecords;
4928     char *recordSchema;
4929     char *recordPacking;
4930     char *database;
4931 } Z_SRW_searchRetrieveRequest;
4932     </synopsis>
4933     Please observe that data of type xsd:string is represented
4934     as a char pointer (<literal>char *</literal>). A null pointer
4935     means that the element is absent.
4936     Data of type xsd:integer is representd as a pointer to
4937     an int (<literal>int *</literal>). Again, a null pointer
4938     us used for absent elements.
4939    </para>
4940    <para>
4941     The SearchRetrieveResponse has the following definition.
4942     <synopsis>
4943 typedef struct {
4944     int * numberOfRecords;
4945     char * resultSetId;
4946     int * resultSetIdleTime;
4947
4948     Z_SRW_record *records;
4949     int num_records;
4950
4951     Z_SRW_diagnostic *diagnostics;
4952     int num_diagnostics;
4953     int *nextRecordPosition;
4954 } Z_SRW_searchRetrieveResponse;
4955     </synopsis>
4956     The <literal>num_records</literal> and <literal>num_diagnostics</literal>
4957     is number of returned records and diagnostics respectively and also
4958     correspond to the "size of" arrays <literal>records</literal>
4959     and <literal>diagnostics</literal>.
4960    </para>
4961    <para>
4962     A retrieval record is defined as follows:
4963     <synopsis>
4964 typedef struct {
4965     char *recordSchema;
4966     char *recordData_buf;
4967     int recordData_len;
4968     int *recordPosition;
4969 } Z_SRW_record;
4970     </synopsis>
4971     The record data is defined as a buffer of some length so that
4972     data can be of any type. SRW 1.0 currenly doesn't allow for this
4973     (only XML), but future versions might do.
4974    </para>
4975    <para>
4976     And, a diagnostic as:
4977     <synopsis>
4978 typedef struct {
4979     int  *code;
4980     char *details;
4981 } Z_SRW_diagnostic;
4982     </synopsis>
4983    </para>
4984   </sect1>
4985  </chapter>
4986  <chapter id="tools">
4987   <title>Supporting Tools</title>
4988   <para>
4989    In support of the service API - primarily the ASN module, which
4990    provides the pro-grammatic interface to the Z39.50 APDUs, &yaz; contains
4991    a collection of tools that support the development of applications.
4992   </para>
4993   <sect1 id="tools.query">
4994    <title>Query Syntax Parsers</title>
4995    <para>
4996     Since the type-1 (RPN) query structure has no direct, useful string
4997     representation, every origin application needs to provide some form of
4998     mapping from a local query notation or representation to a
4999     <token>Z_RPNQuery</token> structure. Some programmers will prefer to
5000     construct the query manually, perhaps using
5001     <function>odr_malloc()</function> to simplify memory management.
5002     The &yaz; distribution includes three separate, query-generating tools
5003     that may be of use to you.
5004    </para>
5005    <sect2 id="PQF">
5006     <title>Prefix Query Format</title>
5007     <para>
5008      Since RPN or reverse polish notation is really just a fancy way of
5009      describing a suffix notation format (operator follows operands), it
5010      would seem that the confusion is total when we now introduce a prefix
5011      notation for RPN. The reason is one of simple laziness - it's somewhat
5012      simpler to interpret a prefix format, and this utility was designed
5013      for maximum simplicity, to provide a baseline representation for use
5014      in simple test applications and scripting environments (like Tcl). The
5015      demonstration client included with YAZ uses the PQF.
5016     </para>
5017     <note>
5018      <para>
5019       The PQF have been adopted by other parties developing Z39.50
5020       software. It is often referred to as Prefix Query Notation
5021       - PQN.
5022      </para>
5023     </note>
5024     <para>
5025      The PQF is defined by the pquery module in the YAZ library.
5026      There are two sets of function that have similar behavior. First
5027      set operates on a PQF parser handle, second set doesn't. First set
5028      set of functions are more flexible than the second set. Second set
5029      is obsolete and is only provided to ensure backwards compatibility.
5030     </para>
5031     <para>
5032      First set of functions all operate on a PQF parser handle:
5033     </para>
5034     <synopsis>
5035      #include &lt;yaz/pquery.h&gt;
5036
5037      YAZ_PQF_Parser yaz_pqf_create(void);
5038
5039      void yaz_pqf_destroy(YAZ_PQF_Parser p);
5040
5041      Z_RPNQuery *yaz_pqf_parse(YAZ_PQF_Parser p, ODR o, const char *qbuf);
5042
5043      Z_AttributesPlusTerm *yaz_pqf_scan(YAZ_PQF_Parser p, ODR o,
5044                           Odr_oid **attributeSetId, const char *qbuf);
5045
5046      int yaz_pqf_error(YAZ_PQF_Parser p, const char **msg, size_t *off);
5047     </synopsis>
5048     <para>
5049      A PQF parser is created and destructed by functions
5050      <function>yaz_pqf_create</function> and
5051      <function>yaz_pqf_destroy</function> respectively.
5052      Function <function>yaz_pqf_parse</function> parses query given
5053      by string <literal>qbuf</literal>. If parsing was successful,
5054      a Z39.50 RPN Query is returned which is created using ODR stream
5055      <literal>o</literal>. If parsing failed, a NULL pointer is
5056      returned.
5057      Function <function>yaz_pqf_scan</function> takes a scan query in
5058      <literal>qbuf</literal>. If parsing was successful, the function
5059      returns attributes plus term pointer and modifies
5060      <literal>attributeSetId</literal> to hold attribute set for the
5061      scan request - both allocated using ODR stream <literal>o</literal>.
5062      If parsing failed, yaz_pqf_scan returns a NULL pointer.
5063      Error information for bad queries can be obtained by a call to
5064      <function>yaz_pqf_error</function> which returns an error code and
5065      modifies <literal>*msg</literal> to point to an error description,
5066      and modifies <literal>*off</literal> to the offset within last
5067      query were parsing failed.
5068     </para>
5069     <para>
5070      The second set of functions are declared as follows:
5071     </para>
5072     <synopsis>
5073      #include &lt;yaz/pquery.h&gt;
5074
5075      Z_RPNQuery *p_query_rpn(ODR o, oid_proto proto, const char *qbuf);
5076
5077      Z_AttributesPlusTerm *p_query_scan(ODR o, oid_proto proto,
5078                              Odr_oid **attributeSetP, const char *qbuf);
5079
5080      int p_query_attset(const char *arg);
5081     </synopsis>
5082     <para>
5083      The function <function>p_query_rpn()</function> takes as arguments an
5084      &odr; stream (see section <link linkend="odr">The ODR Module</link>)
5085      to provide a memory source (the structure created is released on
5086      the next call to <function>odr_reset()</function> on the stream), a
5087      protocol identifier (one of the constants <token>PROTO_Z3950</token> and
5088      <token>PROTO_SR</token>), an attribute set reference, and
5089      finally a null-terminated string holding the query string.
5090     </para>
5091     <para>
5092      If the parse went well, <function>p_query_rpn()</function> returns a
5093      pointer to a <literal>Z_RPNQuery</literal> structure which can be
5094      placed directly into a <literal>Z_SearchRequest</literal>.
5095      If parsing failed, due to syntax error, a NULL pointer is returned.
5096     </para>
5097     <para>
5098      The <literal>p_query_attset</literal> specifies which attribute set
5099      to use if the query doesn't specify one by the
5100      <literal>@attrset</literal> operator.
5101      The <literal>p_query_attset</literal> returns 0 if the argument is a
5102      valid attribute set specifier; otherwise the function returns -1.
5103     </para>
5104     <para>
5105      The grammar of the PQF is as follows:
5106     </para>
5107     <literallayout>
5108      query ::= top-set query-struct.
5109
5110      top-set ::= [ '@attrset' string ]
5111
5112      query-struct ::= attr-spec | simple | complex | '@term' term-type query
5113
5114      attr-spec ::= '@attr' [ string ] string query-struct
5115
5116      complex ::= operator query-struct query-struct.
5117
5118      operator ::= '@and' | '@or' | '@not' | '@prox' proximity.
5119
5120      simple ::= result-set | term.
5121
5122      result-set ::= '@set' string.
5123
5124      term ::= string.
5125
5126      proximity ::= exclusion distance ordered relation which-code unit-code.
5127
5128      exclusion ::= '1' | '0' | 'void'.
5129
5130      distance ::= integer.
5131
5132      ordered ::= '1' | '0'.
5133
5134      relation ::= integer.
5135
5136      which-code ::= 'known' | 'private' | integer.
5137
5138      unit-code ::= integer.
5139
5140      term-type ::= 'general' | 'numeric' | 'string' | 'oid' | 'datetime' | 'null'.
5141     </literallayout>
5142     <para>
5143      You will note that the syntax above is a fairly faithful
5144      representation of RPN, except for the Attribute, which has been
5145      moved a step away from the term, allowing you to associate one or more
5146      attributes with an entire query structure. The parser will
5147      automatically apply the given attributes to each term as required.
5148     </para>
5149     <para>
5150      The @attr operator is followed by an attribute specification
5151      (<literal>attr-spec</literal> above). The specification consists
5152      of an optional attribute set, an attribute type-value pair and
5153      a sub-query. The attribute type-value pair is packed in one string:
5154      an attribute type, an equals sign, and an attribute value, like this:
5155      <literal>@attr 1=1003</literal>.
5156      The type is always an integer but the value may be either an
5157      integer or a string (if it doesn't start with a digit character).
5158      A string attribute-value is encoded as a Type-1 ``complex''
5159      attribute with the list of values containing the single string
5160      specified, and including no semantic indicators.
5161     </para>
5162     <para>
5163      Version 3 of the Z39.50 specification defines various encoding of terms.
5164      Use <literal>@term </literal> <replaceable>type</replaceable>
5165      <replaceable>string</replaceable>,
5166      where type is one of: <literal>general</literal>,
5167      <literal>numeric</literal> or <literal>string</literal>
5168      (for InternationalString).
5169      If no term type has been given, the <literal>general</literal> form
5170      is used.  This is the only encoding allowed in both versions 2 and 3
5171      of the Z39.50 standard.
5172     </para>
5173     <sect3 id="PQF-prox">
5174      <title>Using Proximity Operators with PQF</title>
5175      <note>
5176       <para>
5177        This is an advanced topic, describing how to construct
5178        queries that make very specific requirements on the
5179        relative location of their operands.
5180        You may wish to skip this section and go straight to
5181        <link linkend="pqf-examples">the example PQF queries</link>.
5182       </para>
5183       <para>
5184        <warning>
5185         <para>
5186          Most Z39.50 servers do not support proximity searching, or
5187          support only a small subset of the full functionality that
5188          can be expressed using the PQF proximity operator.  Be
5189          aware that the ability to <emphasis>express</emphasis> a
5190          query in PQF is no guarantee that any given server will
5191          be able to <emphasis>execute</emphasis> it.
5192         </para>
5193        </warning>
5194       </para>
5195      </note>
5196      <para>
5197       The proximity operator <literal>@prox</literal> is a special
5198       and more restrictive version of the conjunction operator
5199       <literal>@and</literal>.  Its semantics are described in
5200       section 3.7.2 (Proximity) of Z39.50 the standard itself, which
5201       can be read on-line at
5202       <ulink url="&url.z39.50.proximity;"/>
5203      </para>
5204      <para>
5205       In PQF, the proximity operation is represented by a sequence
5206       of the form
5207       <screen>
5208        @prox <replaceable>exclusion</replaceable> <replaceable>distance</replaceable> <replaceable>ordered</replaceable> <replaceable>relation</replaceable> <replaceable>which-code</replaceable> <replaceable>unit-code</replaceable>
5209       </screen>
5210       in which the meanings of the parameters are as described in in
5211       the standard, and they can take the following values:
5212       <itemizedlist>
5213        <listitem>
5214         <formalpara><title>exclusion</title>
5215         <para>
5216          0 = false (i.e. the proximity condition specified by the
5217          remaining parameters must be satisfied) or
5218          1 = true (the proximity condition specified by the
5219          remaining parameters must <emphasis>not</emphasis> be
5220          satisifed).
5221         </para>
5222        </formalpara>
5223        </listitem>
5224        <listitem>
5225         <formalpara><title>distance</title><para>
5226         An integer specifying the difference between the locations
5227         of the operands: e.g. two adjacent words would have
5228         distance=1 since their locations differ by one unit.
5229        </para>
5230        </formalpara></listitem>
5231        <listitem>
5232         <formalpara><title>ordered</title><para>
5233         1 = ordered (the operands must occur in the order the
5234         query specifies them) or
5235         0 = unordered (they may appear in either order).
5236        </para>
5237        </formalpara>
5238        </listitem>
5239        <listitem>
5240         <formalpara><title>relation</title><para>
5241         Recognised values are
5242         1 (lessThan),
5243         2 (lessThanOrEqual),
5244         3 (equal),
5245         4 (greaterThanOrEqual),
5246         5 (greaterThan) and
5247         6 (notEqual).
5248        </para>
5249        </formalpara>
5250        </listitem>
5251        <listitem>
5252         <formalpara><title>which-code</title><para>
5253         <literal>known</literal>
5254         or
5255         <literal>k</literal>
5256         (the unit-code parameter is taken from the well-known list
5257         of alternatives described in below) or
5258         <literal>private</literal>
5259         or
5260         <literal>p</literal>
5261         (the unit-code paramater has semantics specific to an
5262         out-of-band agreement such as a profile).
5263        </para>
5264        </formalpara>
5265        </listitem>
5266        <listitem>
5267         <formalpara><title>unit-code</title><para>
5268         If the which-code parameter is <literal>known</literal>
5269         then the recognised values are
5270         1 (character),
5271         2 (word),
5272         3 (sentence),
5273         4 (paragraph),
5274         5 (section),
5275         6 (chapter),
5276         7 (document),
5277         8 (element),
5278         9 (subelement),
5279         10 (elementType) and
5280         11 (byte).
5281         If which-code is <literal>private</literal> then the
5282         acceptable values are determined by the profile.
5283        </para>
5284         </formalpara>
5285        </listitem>
5286       </itemizedlist>
5287       (The numeric values of the relation and well-known unit-code
5288       parameters are taken straight from
5289       <ulink url="&url.z39.50.proximity.asn1;"
5290              >the ASN.1</ulink> of the proximity structure in the standard.)
5291      </para>
5292     </sect3>
5293     <sect3 id="pqf-examples">
5294      <title>PQF queries</title>
5295      <example id="example.pqf.simple.terms">
5296       <title>PQF queries using simple terms</title>
5297       <para>
5298        <screen>
5299         dylan
5300
5301         "bob dylan"
5302        </screen>
5303       </para>
5304      </example>
5305      <example id="pqf.example.pqf.boolean.operators">
5306       <title>PQF boolean operators</title>
5307       <para>
5308        <screen>
5309         @or "dylan" "zimmerman"
5310
5311         @and @or dylan zimmerman when
5312
5313         @and when @or dylan zimmerman
5314        </screen>
5315       </para>
5316      </example>
5317      <example id="example.pqf.result.sets">
5318       <title>PQF references to result sets</title>
5319       <para>
5320        <screen>
5321         @set Result-1
5322
5323         @and @set seta @set setb
5324        </screen>
5325       </para>
5326      </example>
5327      <example id="example.pqf.attributes">
5328       <title>Attributes for terms</title>
5329       <para>
5330        <screen>
5331         @attr 1=4 computer
5332
5333         @attr 1=4 @attr 4=1 "self portrait"
5334
5335         @attrset exp1 @attr 1=1 CategoryList
5336
5337         @attr gils 1=2008 Copenhagen
5338
5339         @attr 1=/book/title computer
5340        </screen>
5341       </para>
5342      </example>
5343      <example id="example.pqf.proximity">
5344       <title>PQF Proximity queries</title>
5345       <para>
5346        <screen>
5347         @prox 0 3 1 2 k 2 dylan zimmerman
5348        </screen>
5349        Here the parameters 0, 3, 1, 2, k and 2 represent exclusion,
5350        distance, ordered, relation, which-code and unit-code, in that
5351        order.  So:
5352        <itemizedlist>
5353         <listitem>
5354          <para>exclusion = 0: the proximity condition must hold</para>
5355         </listitem>
5356         <listitem>
5357          <para>distance = 3: the terms must be three units apart</para>
5358         </listitem>
5359         <listitem>
5360          <para>
5361           ordered = 1: they must occur in the order they are specified
5362         </para>
5363         </listitem>
5364         <listitem>
5365          <para>
5366         relation = 2: lessThanOrEqual (to the distance of 3 units)
5367         </para>
5368         </listitem>
5369         <listitem>
5370          <para>
5371           which-code is ``known'', so the standard unit-codes are used
5372          </para>
5373         </listitem>
5374         <listitem>
5375          <para>unit-code = 2: word.</para>
5376         </listitem>
5377        </itemizedlist>
5378        So the whole proximity query means that the words
5379        <literal>dylan</literal> and <literal>zimmerman</literal> must
5380        both occur in the record, in that order, differing in position
5381        by three or fewer words (i.e. with two or fewer words between
5382        them.)  The query would find ``Bob Dylan, aka. Robert
5383        Zimmerman'', but not ``Bob Dylan, born as Robert Zimmerman''
5384        since the distance in this case is four.
5385       </para>
5386      </example>
5387      <example id="example.pqf.search.term.type">
5388       <title>PQF specification of search term type</title>
5389       <para>
5390        <screen>
5391         @term string "a UTF-8 string, maybe?"
5392        </screen>
5393       </para>
5394      </example>
5395      <example id="example.pqf.mixed.queries">
5396       <title>PQF mixed queries</title>
5397       <para>
5398        <screen>
5399         @or @and bob dylan @set Result-1
5400
5401         @attr 4=1 @and @attr 1=1 "bob dylan" @attr 1=4 "slow train coming"
5402
5403         @and @attr 2=4 @attr gils 1=2038 -114 @attr 2=2 @attr gils 1=2039 -109
5404        </screen>
5405        The last of these examples is a spatial search: in
5406        <ulink url="http://www.gils.net/prof_v2.html#sec_7_4"
5407               >the GILS attribute set</ulink>,
5408        access point
5409        2038 indicates West Bounding Coordinate and
5410        2030 indicates East Bounding Coordinate,
5411        so the query is for areas extending from -114 degrees
5412        to no more than -109 degrees.
5413       </para>
5414      </example>
5415     </sect3>
5416    </sect2>
5417    <sect2 id="CCL"><title>CCL</title>
5418     <para>
5419      Not all users enjoy typing in prefix query structures and numerical
5420      attribute values, even in a minimalistic test client. In the library
5421      world, the more intuitive Common Command Language - CCL (ISO 8777)
5422      has enjoyed some popularity - especially before the widespread
5423      availability of graphical interfaces. It is still useful in
5424      applications where you for some reason or other need to provide a
5425      symbolic language for expressing boolean query structures.
5426     </para>
5427     <sect3 id="ccl.syntax">
5428      <title>CCL Syntax</title>
5429      <para>
5430       The CCL parser obeys the following grammar for the FIND argument.
5431       The syntax is annotated by in the lines prefixed by
5432       <literal>--</literal>.
5433      </para>
5434      <screen>
5435       CCL-Find ::= CCL-Find Op Elements
5436                 | Elements.
5437
5438       Op ::= "and" | "or" | "not"
5439       -- The above means that Elements are separated by boolean operators.
5440
5441       Elements ::= '(' CCL-Find ')'
5442                 | Set
5443                 | Terms
5444                 | Qualifiers Relation Terms
5445                 | Qualifiers Relation '(' CCL-Find ')'
5446                 | Qualifiers '=' string '-' string
5447       -- Elements is either a recursive definition, a result set reference, a
5448       -- list of terms, qualifiers followed by terms, qualifiers followed
5449       -- by a recursive definition or qualifiers in a range (lower - upper).
5450
5451       Set ::= 'set' = string
5452       -- Reference to a result set
5453
5454       Terms ::= Terms Prox Term
5455              | Term
5456       -- Proximity of terms.
5457
5458       Term ::= Term string
5459             | string
5460       -- This basically means that a term may include a blank
5461
5462       Qualifiers ::= Qualifiers ',' string
5463                   | string
5464       -- Qualifiers is a list of strings separated by comma
5465
5466       Relation ::= '=' | '>=' | '&lt;=' | '&lt;>' | '>' | '&lt;'
5467       -- Relational operators. This really doesn't follow the ISO8777
5468       -- standard.
5469
5470       Prox ::= '%' | '!'
5471       -- Proximity operator
5472
5473      </screen>
5474      <example id="example.ccl.queries">
5475       <title>CCL queries</title>
5476       <para>
5477        The following queries are all valid:
5478       </para>
5479       <screen>
5480        dylan
5481
5482        "bob dylan"
5483
5484        dylan or zimmerman
5485
5486        set=1
5487
5488        (dylan and bob) or set=1
5489
5490        righttrunc?
5491
5492        "notrunc?"
5493
5494        singlechar#mask
5495       </screen>
5496       <para>
5497        Assuming that the qualifiers <literal>ti</literal>,
5498        <literal>au</literal>
5499        and <literal>date</literal> are defined we may use:
5500       </para>
5501       <screen>
5502        ti=self portrait
5503
5504        au=(bob dylan and slow train coming)
5505
5506        date>1980 and (ti=((self portrait)))
5507       </screen>
5508      </example>
5509     </sect3>
5510     <sect3 id="ccl.qualifiers">
5511      <title>CCL Qualifiers</title>
5512      <para>
5513       Qualifiers are used to direct the search to a particular searchable
5514       index, such as title (ti) and author indexes (au). The CCL standard
5515       itself doesn't specify a particular set of qualifiers, but it does
5516       suggest a few short-hand notations. You can customize the CCL parser
5517       to support a particular set of qualifiers to reflect the current target
5518       profile. Traditionally, a qualifier would map to a particular
5519       use-attribute within the BIB-1 attribute set. It is also
5520       possible to set other attributes, such as the structure
5521       attribute.
5522      </para>
5523      <para>
5524       A  CCL profile is a set of predefined CCL qualifiers that may be
5525       read from a file or set in the CCL API.
5526       The YAZ client reads its CCL qualifiers from a file named
5527       <filename>default.bib</filename>. There are four types of
5528       lines in a CCL profile: qualifier specification,
5529       qualifier alias, comments and directives.
5530      </para>
5531      <sect4 id="ccl.qualifier.specification">
5532       <title>Qualifier specification</title>
5533       <para>
5534        A qualifier specification is of the form:
5535       </para>
5536       <para>
5537        <replaceable>qualifier-name</replaceable>
5538        [<replaceable>attributeset</replaceable><literal>,</literal>]<replaceable>type</replaceable><literal>=</literal><replaceable>val</replaceable>
5539        [<replaceable>attributeset</replaceable><literal>,</literal>]<replaceable>type</replaceable><literal>=</literal><replaceable>val</replaceable> ...
5540       </para>
5541       <para>
5542        where <replaceable>qualifier-name</replaceable> is the name of the
5543        qualifier to be used (eg. <literal>ti</literal>),
5544        <replaceable>type</replaceable> is attribute type in the attribute
5545        set (Bib-1 is used if no attribute set is given) and
5546        <replaceable>val</replaceable> is attribute value.
5547        The <replaceable>type</replaceable> can be specified as an
5548        integer or as it be specified either as a single-letter:
5549        <literal>u</literal> for use,
5550        <literal>r</literal> for relation,<literal>p</literal> for position,
5551        <literal>s</literal> for structure,<literal>t</literal> for truncation
5552        or <literal>c</literal> for completeness.
5553        The attributes for the special qualifier name <literal>term</literal>
5554        are used when no CCL qualifier is given in a query.
5555        <table id="ccl.common.bib1.attributes">
5556         <title>Common Bib-1 attributes</title>
5557         <tgroup cols="2">
5558          <colspec colwidth="2*" colname="type"></colspec>
5559          <colspec colwidth="9*" colname="description"></colspec>
5560          <thead>
5561           <row>
5562            <entry>Type</entry>
5563            <entry>Description</entry>
5564           </row>
5565          </thead>
5566          <tbody>
5567           <row>
5568            <entry><literal>u=</literal><replaceable>value</replaceable></entry>
5569            <entry>
5570             Use attribute (1). Common use attributes are
5571             1 Personal-name, 4 Title, 7 ISBN, 8 ISSN, 30 Date,
5572             62 Subject, 1003 Author), 1016 Any. Specify value
5573             as an integer.
5574            </entry>
5575           </row>
5576           <row>
5577            <entry><literal>r=</literal><replaceable>value</replaceable></entry>
5578            <entry>
5579             Relation attribute (2). Common values are
5580             1 &lt;, 2 &lt;=, 3 =, 4 &gt;=, 5 &gt;, 6 &lt;&gt;,
5581             100 phonetic, 101 stem, 102 relevance, 103 always matches.
5582            </entry>
5583           </row>
5584           <row>
5585            <entry><literal>p=</literal><replaceable>value</replaceable></entry>
5586            <entry>
5587             Position attribute (3). Values: 1 first in field, 2
5588             first in any subfield, 3 any position in field.
5589            </entry>
5590           </row>
5591           <row>
5592            <entry><literal>s=</literal><replaceable>value</replaceable></entry>
5593            <entry>
5594             Structure attribute (4). Values: 1 phrase, 2 word,
5595             3 key, 4 year, 5 date, 6 word list, 100 date (un),
5596             101 name (norm), 102 name (un), 103 structure, 104 urx,
5597             105 free-form-text, 106 document-text, 107 local-number,
5598             108 string, 109 numeric string.
5599            </entry>
5600           </row>
5601           <row>
5602            <entry><literal>t=</literal><replaceable>value</replaceable></entry>
5603            <entry>
5604             Truncation attribute (5). Values: 1 right, 2 left,
5605             3 left&amp; right, 100 none, 101 process #, 102 regular-1,
5606             103 regular-2, 104 CCL.
5607            </entry>
5608           </row>
5609           <row>
5610            <entry><literal>c=</literal><replaceable>value</replaceable></entry>
5611            <entry>
5612             Completeness attribute (6). Values: 1 incomplete subfield,
5613             2 complete subfield, 3 complete field.
5614            </entry>
5615           </row>
5616          </tbody>
5617         </tgroup>
5618        </table>
5619       </para>
5620       <para>
5621        Refer to <xref linkend="bib1"/> or the complete
5622        <ulink url="&url.z39.50.attset.bib1;">list of Bib-1 attributes</ulink>
5623       </para>
5624       <para>
5625        It is also possible to specify non-numeric attribute values,
5626        which are used in combination with certain types.
5627        The special combinations are:
5628        <table id="ccl.special.attribute.combos">
5629         <title>Special attribute combos</title>
5630         <tgroup cols="2">
5631          <colspec colwidth="2*" colname="name"></colspec>
5632          <colspec colwidth="9*" colname="description"></colspec>
5633          <thead>
5634           <row>
5635            <entry>Name</entry>
5636            <entry>Description</entry>
5637           </row>
5638          </thead>
5639          <tbody>
5640           <row>
5641            <entry><literal>s=pw</literal></entry>
5642            <entry>
5643             The structure is set to either word or phrase depending
5644             on the number of tokens in a term (phrase-word).
5645            </entry>
5646           </row>
5647           <row>
5648            <entry><literal>s=al</literal></entry>
5649            <entry>
5650             Each token in the term is ANDed. (and-list).
5651             This does not set the structure at all.
5652            </entry>
5653           </row>
5654           <row><entry><literal>s=ol</literal></entry>
5655           <entry>
5656            Each token in the term is ORed. (or-list).
5657            This does not set the structure at all.
5658           </entry>
5659           </row>
5660           <row><entry><literal>s=ag</literal></entry>
5661           <entry>
5662            Tokens that appears as phrases (with blank in them) gets
5663            structure phrase attached (4=1). Tokens that appear to be words
5664            gets structure word attached (4=2). Phrases and words are
5665            ANDed. This is a variant of s=al and s=pw, with the main
5666            difference that words are not split (with operator AND)
5667            but instead kept in one RPN token. This facility appeared
5668            in YAZ 4.2.38.
5669           </entry>
5670           </row>
5671           <row><entry><literal>r=o</literal></entry>
5672           <entry>
5673            Allows ranges and the operators greather-than, less-than, ...
5674            equals.
5675            This sets Bib-1 relation attribute accordingly (relation
5676            ordered). A query construct is only treated as a range if
5677            dash is used and that is surrounded by white-space. So
5678            <literal>-1980</literal> is treated as term
5679            <literal>"-1980"</literal> not <literal>&lt;= 1980</literal>.
5680            If <literal>- 1980</literal> is used, however, that is
5681            treated as a range.
5682           </entry>
5683           </row>
5684           <row><entry><literal>r=r</literal></entry>
5685           <entry>
5686            Similar to <literal>r=o</literal> but assumes that terms
5687            are non-negative (not prefixed with <literal>-</literal>).
5688            Thus, a dash will always be treated as a range.
5689            The construct <literal>1980-1990</literal> is
5690            treated as a range with <literal>r=r</literal> but as a
5691            single term <literal>"1980-1990"</literal> with
5692            <literal>r=o</literal>. The special attribute
5693            <literal>r=r</literal> is available in YAZ 2.0.24 or later.
5694           </entry>
5695           </row>
5696           <row><entry><literal>r=omiteq</literal></entry>
5697           <entry>
5698            This will omit relation=equals (@attr 2=3) when r=o / r=r
5699            is used. This is useful for servers that somehow breaks
5700            when an explicit relation=equals is used. Omitting the
5701            relation is usually safe because "equals" is the default
5702            behavior. This tweak was added in YAZ version 5.1.2.
5703           </entry>
5704           </row>
5705           <row><entry><literal>t=l</literal></entry>
5706           <entry>
5707            Allows term to be left-truncated.
5708            If term is of the form <literal>?x</literal>, the resulting
5709            Type-1 term is <literal>x</literal> and truncation is left.
5710           </entry>
5711           </row>
5712           <row><entry><literal>t=r</literal></entry>
5713           <entry>
5714            Allows term to be right-truncated.
5715            If term is of the form <literal>x?</literal>, the resulting
5716            Type-1 term is <literal>x</literal> and truncation is right.
5717           </entry>
5718           </row>
5719           <row><entry><literal>t=n</literal></entry>
5720           <entry>
5721            If term is does not include <literal>?</literal>, the
5722            truncation attribute is set to none (100).
5723           </entry>
5724           </row>
5725           <row><entry><literal>t=b</literal></entry>
5726           <entry>
5727            Allows term to be both left&amp;right truncated.
5728            If term is of the form <literal>?x?</literal>, the
5729            resulting term is <literal>x</literal> and trunctation is
5730            set to both left&amp;right.
5731           </entry>
5732           </row>
5733           <row><entry><literal>t=x</literal></entry>
5734           <entry>
5735            Allows masking anywhere in a term, thus fully supporting
5736            # (mask one character) and ? (zero or more of any).
5737            If masking is used, trunction is set to 102 (regexp-1 in term)
5738            and the term is converted accordingly to a regular expression.
5739           </entry>
5740           </row>
5741           <row><entry><literal>t=z</literal></entry>
5742           <entry>
5743            Allows masking anywhere in a term, thus fully supporting
5744            # (mask one character) and ? (zero or more of any).
5745            If masking is used, trunction is set to 104 (Z39.58 in term)
5746            and the term is converted accordingly to Z39.58 masking term -
5747            actually the same truncation as CCL itself.
5748           </entry>
5749           </row>
5750          </tbody>
5751         </tgroup>
5752        </table>
5753       </para>
5754       <example id="example.ccl.profile">
5755        <title>CCL profile</title>
5756        <para>
5757         Consider the following definition:
5758        </para>
5759        <screen>
5760         ti       u=4 s=1
5761         au       u=1 s=1
5762         term     s=105
5763         ranked   r=102
5764         date     u=30 r=o
5765        </screen>
5766        <para>
5767         <literal>ti</literal> and <literal>au</literal> both set
5768         structure attribute to phrase (s=1).
5769         <literal>ti</literal>
5770         sets the use-attribute to 4. <literal>au</literal> sets the
5771         use-attribute to 1.
5772         When no qualifiers are used in the query the structure-attribute is
5773         set to free-form-text (105) (rule for <literal>term</literal>).
5774         The <literal>date</literal> sets the relation attribute to
5775         the relation used in the CCL query and sets the use attribute
5776         to 30 (Bib-1 Date).
5777        </para>
5778        <para>
5779         You can combine attributes. To Search for "ranked title" you
5780         can do
5781         <screen>
5782          ti,ranked=knuth computer
5783         </screen>
5784         which will set relation=ranked, use=title, structure=phrase.
5785        </para>
5786        <para>
5787         Query
5788         <screen>
5789          date > 1980
5790         </screen>
5791         is a valid query. But
5792         <screen>
5793          ti > 1980
5794         </screen>
5795         is invalid.
5796        </para>
5797       </example>
5798      </sect4>
5799      <sect4 id="ccl.qualifier.alias">
5800       <title>Qualifier alias</title>
5801       <para>
5802        A qualifier alias is of the form:
5803       </para>
5804       <para>
5805        <replaceable>q</replaceable>
5806        <replaceable>q1</replaceable> <replaceable>q2</replaceable> ..
5807       </para>
5808       <para>
5809        which declares <replaceable>q</replaceable> to
5810        be an alias for <replaceable>q1</replaceable>,
5811        <replaceable>q2</replaceable>... such that the CCL
5812        query <replaceable>q=x</replaceable> is equivalent to
5813        <replaceable>q1=x or q2=x or ...</replaceable>.
5814       </para>
5815      </sect4>
5816      <sect4 id="ccl.comments">
5817       <title>Comments</title>
5818       <para>
5819        Lines with white space or lines that begin with
5820        character <literal>#</literal> are treated as comments.
5821       </para>
5822      </sect4>
5823      <sect4 id="ccl.directives">
5824       <title>Directives</title>
5825       <para>
5826        Directive specifications takes the form
5827       </para>
5828       <para><literal>@</literal><replaceable>directive</replaceable> <replaceable>value</replaceable>
5829       </para>
5830       <table id="ccl.directives.table">
5831        <title>CCL directives</title>
5832        <tgroup cols="3">
5833         <colspec colwidth="2*" colname="name"></colspec>
5834         <colspec colwidth="8*" colname="description"></colspec>
5835         <colspec colwidth="1*" colname="default"></colspec>
5836         <thead>
5837          <row>
5838           <entry>Name</entry>
5839           <entry>Description</entry>
5840           <entry>Default</entry>
5841          </row>
5842         </thead>
5843         <tbody>
5844          <row>
5845           <entry>truncation</entry>
5846           <entry>Truncation character</entry>
5847           <entry><literal>?</literal></entry>
5848          </row>
5849          <row>
5850           <entry>mask</entry>
5851           <entry>Masking character. Requires YAZ 4.2.58 or later</entry>
5852           <entry><literal>#</literal></entry>
5853          </row>
5854          <row>
5855           <entry>field</entry>
5856           <entry>Specifies how multiple fields are to be
5857            combined. There are two modes: <literal>or</literal>:
5858            multiple qualifier fields are ORed,
5859            <literal>merge</literal>: attributes for the qualifier
5860            fields are merged and assigned to one term.
5861            </entry>
5862           <entry><literal>merge</literal></entry>
5863          </row>
5864          <row>
5865           <entry>case</entry>
5866           <entry>Specifies if CCL operators and qualifiers should be
5867            compared with case sensitivity or not. Specify 1 for
5868            case sensitive; 0 for case insensitive.</entry>
5869           <entry><literal>1</literal></entry>
5870          </row>
5871          <row>
5872           <entry>and</entry>
5873           <entry>Specifies token for CCL operator AND.</entry>
5874           <entry><literal>and</literal></entry>
5875          </row>
5876          <row>
5877           <entry>or</entry>
5878           <entry>Specifies token for CCL operator OR.</entry>
5879           <entry><literal>or</literal></entry>
5880          </row>
5881          <row>
5882           <entry>not</entry>
5883           <entry>Specifies token for CCL operator NOT.</entry>
5884           <entry><literal>not</literal></entry>
5885          </row>
5886          <row>
5887           <entry>set</entry>
5888           <entry>Specifies token for CCL operator SET.</entry>
5889           <entry><literal>set</literal></entry>
5890          </row>
5891         </tbody>
5892        </tgroup>
5893       </table>
5894      </sect4>
5895     </sect3>
5896     <sect3 id="ccl.api">
5897      <title>CCL API</title>
5898      <para>
5899       All public definitions can be found in the header file
5900       <filename>ccl.h</filename>. A profile identifier is of type
5901       <literal>CCL_bibset</literal>. A profile must be created with the call
5902       to the function <function>ccl_qual_mk</function> which returns a profile
5903       handle of type <literal>CCL_bibset</literal>.
5904      </para>
5905      <para>
5906       To read a file containing qualifier definitions the function
5907       <function>ccl_qual_file</function> may be convenient. This function
5908       takes an already opened <literal>FILE</literal> handle pointer as
5909       argument along with a <literal>CCL_bibset</literal> handle.
5910      </para>
5911      <para>
5912       To parse a simple string with a FIND query use the function
5913      </para>
5914      <screen>
5915 struct ccl_rpn_node *ccl_find_str(CCL_bibset bibset, const char *str,
5916                                   int *error, int *pos);
5917      </screen>
5918      <para>
5919       which takes the CCL profile (<literal>bibset</literal>) and query
5920       (<literal>str</literal>) as input. Upon successful completion the RPN
5921       tree is returned. If an error occur, such as a syntax error, the integer
5922       pointed to by <literal>error</literal> holds the error code and
5923       <literal>pos</literal> holds the offset inside query string in which
5924       the parsing failed.
5925      </para>
5926      <para>
5927       An English representation of the error may be obtained by calling
5928       the <literal>ccl_err_msg</literal> function. The error codes are
5929       listed in <filename>ccl.h</filename>.
5930      </para>
5931      <para>
5932       To convert the CCL RPN tree (type
5933       <literal>struct ccl_rpn_node *</literal>)
5934       to the Z_RPNQuery of YAZ the function <function>ccl_rpn_query</function>
5935       must be used. This function which is part of YAZ is implemented in
5936       <filename>yaz-ccl.c</filename>.
5937       After calling this function the CCL RPN tree is probably no longer
5938       needed. The <literal>ccl_rpn_delete</literal> destroys the CCL RPN tree.
5939      </para>
5940      <para>
5941       A CCL profile may be destroyed by calling the
5942       <function>ccl_qual_rm</function> function.
5943      </para>
5944      <para>
5945       The token names for the CCL operators may be changed by setting the
5946       globals (all type <literal>char *</literal>)
5947       <literal>ccl_token_and</literal>, <literal>ccl_token_or</literal>,
5948       <literal>ccl_token_not</literal> and <literal>ccl_token_set</literal>.
5949       An operator may have aliases, i.e. there may be more than one name for
5950       the operator. To do this, separate each alias with a space character.
5951      </para>
5952     </sect3>
5953    </sect2>
5954    <sect2 id="cql">
5955     <title>CQL</title>
5956     <para>
5957      <ulink url="&url.cql;">CQL</ulink>
5958      - Common Query Language - was defined for the
5959      <ulink url="&url.sru;">SRU</ulink> protocol.
5960      In many ways CQL has a similar syntax to CCL.
5961      The objective of CQL is different. Where CCL aims to be
5962      an end-user language, CQL is <emphasis>the</emphasis> protocol
5963      query language for SRU.
5964     </para>
5965     <tip>
5966      <para>
5967       If you are new to CQL, read the
5968       <ulink url="&url.cql.intro;">Gentle Introduction</ulink>.
5969      </para>
5970     </tip>
5971     <para>
5972      The CQL parser in &yaz; provides the following:
5973      <itemizedlist>
5974       <listitem>
5975        <para>
5976         It parses and validates a CQL query.
5977        </para>
5978       </listitem>
5979       <listitem>
5980        <para>
5981         It generates a C structure that allows you to convert
5982         a CQL query to some other query language, such as SQL.
5983        </para>
5984       </listitem>
5985       <listitem>
5986        <para>
5987         The parser converts a valid CQL query to PQF, thus providing a
5988         way to use CQL for both SRU servers and Z39.50 targets at the
5989         same time.
5990        </para>
5991       </listitem>
5992       <listitem>
5993        <para>
5994         The parser converts CQL to XCQL.
5995         XCQL is an XML representation of CQL.
5996         XCQL is part of the SRU specification. However, since SRU
5997         supports CQL only, we don't expect XCQL to be widely used.
5998         Furthermore, CQL has the advantage over XCQL that it is
5999         easy to read.
6000        </para>
6001       </listitem>
6002      </itemizedlist>
6003     </para>
6004     <sect3 id="cql.parsing">
6005      <title>CQL parsing</title>
6006      <para>
6007       A CQL parser is represented by the <literal>CQL_parser</literal>
6008       handle. Its contents should be considered &yaz; internal (private).
6009       <synopsis>
6010 #include &lt;yaz/cql.h&gt;
6011
6012 typedef struct cql_parser *CQL_parser;
6013
6014 CQL_parser cql_parser_create(void);
6015 void cql_parser_destroy(CQL_parser cp);
6016       </synopsis>
6017      A parser is created by <function>cql_parser_create</function> and
6018      is destroyed by <function>cql_parser_destroy</function>.
6019      </para>
6020      <para>
6021       To parse a CQL query string, the following function
6022       is provided:
6023       <synopsis>
6024 int cql_parser_string(CQL_parser cp, const char *str);
6025       </synopsis>
6026       A CQL query is parsed by the <function>cql_parser_string</function>
6027       which takes a query <parameter>str</parameter>.
6028       If the query was valid (no syntax errors), then zero is returned;
6029       otherwise -1 is returned to indicate a syntax error.
6030      </para>
6031      <para>
6032       <synopsis>
6033 int cql_parser_stream(CQL_parser cp,
6034                       int (*getbyte)(void *client_data),
6035                       void (*ungetbyte)(int b, void *client_data),
6036                       void *client_data);
6037
6038 int cql_parser_stdio(CQL_parser cp, FILE *f);
6039       </synopsis>
6040       The functions <function>cql_parser_stream</function> and
6041       <function>cql_parser_stdio</function> parses a CQL query
6042       - just like <function>cql_parser_string</function>.
6043       The only difference is that the CQL query can be
6044       fed to the parser in different ways.
6045       The <function>cql_parser_stream</function> uses a generic
6046       byte stream as input. The <function>cql_parser_stdio</function>
6047       uses a <literal>FILE</literal> handle which is opened for reading.
6048      </para>
6049     </sect3>
6050     <sect3 id="cql.tree">
6051      <title>CQL tree</title>
6052      <para>
6053       The the query string is valid, the CQL parser
6054       generates a tree representing the structure of the
6055       CQL query.
6056      </para>
6057      <para>
6058       <synopsis>
6059 struct cql_node *cql_parser_result(CQL_parser cp);
6060       </synopsis>
6061       <function>cql_parser_result</function> returns the
6062       a pointer to the root node of the resulting tree.
6063      </para>
6064      <para>
6065       Each node in a CQL tree is represented by a
6066       <literal>struct cql_node</literal>.
6067       It is defined as follows:
6068       <synopsis>
6069 #define CQL_NODE_ST 1
6070 #define CQL_NODE_BOOL 2
6071 #define CQL_NODE_SORT 3
6072 struct cql_node {
6073     int which;
6074     union {
6075         struct {
6076             char *index;
6077             char *index_uri;
6078             char *term;
6079             char *relation;
6080             char *relation_uri;
6081             struct cql_node *modifiers;
6082         } st;
6083         struct {
6084             char *value;
6085             struct cql_node *left;
6086             struct cql_node *right;
6087             struct cql_node *modifiers;
6088         } boolean;
6089         struct {
6090             char *index;
6091             struct cql_node *next;
6092             struct cql_node *modifiers;
6093             struct cql_node *search;
6094         } sort;
6095     } u;
6096 };
6097       </synopsis>
6098       There are three node types: search term (ST), boolean (BOOL)
6099       and sortby (SORT).
6100       A modifier is treated as a search term too.
6101      </para>
6102      <para>
6103       The search term node has five members:
6104       <itemizedlist>
6105        <listitem>
6106         <para>
6107          <literal>index</literal>: index for search term.
6108          If an index is unspecified for a search term,
6109          <literal>index</literal> will be NULL.
6110         </para>
6111        </listitem>
6112        <listitem>
6113         <para>
6114          <literal>index_uri</literal>: index URi for search term
6115          or NULL if none could be resolved for the index.
6116         </para>
6117        </listitem>
6118        <listitem>
6119         <para>
6120          <literal>term</literal>: the search term itself.
6121         </para>
6122        </listitem>
6123        <listitem>
6124         <para>
6125          <literal>relation</literal>: relation for search term.
6126         </para>
6127        </listitem>
6128        <listitem>
6129         <para>
6130          <literal>relation_uri</literal>: relation URI for search term.
6131         </para>
6132        </listitem>
6133        <listitem>
6134         <para>
6135          <literal>modifiers</literal>: relation modifiers for search
6136          term. The <literal>modifiers</literal> list itself of cql_nodes
6137          each of type <literal>ST</literal>.
6138         </para>
6139        </listitem>
6140       </itemizedlist>
6141      </para>
6142      <para>
6143       The boolean node represents <literal>and</literal>,
6144       <literal>or</literal>, <literal>not</literal> +
6145       proximity.
6146       <itemizedlist>
6147        <listitem>
6148         <para>
6149          <literal>left</literal> and <literal>right</literal>: left
6150          - and right operand respectively.
6151         </para>
6152        </listitem>
6153        <listitem>
6154         <para>
6155          <literal>modifiers</literal>: proximity arguments.
6156         </para>
6157        </listitem>
6158       </itemizedlist>
6159      </para>
6160      <para>
6161       The sort node represents both the SORTBY clause.
6162      </para>
6163     </sect3>
6164     <sect3 id="cql.to.pqf">
6165      <title>CQL to PQF conversion</title>
6166      <para>
6167       Conversion to PQF (and Z39.50 RPN) is tricky by the fact
6168       that the resulting RPN depends on the Z39.50 target
6169       capabilities (combinations of supported attributes).
6170       In addition, the CQL and SRU operates on index prefixes
6171       (URI or strings), whereas the RPN uses Object Identifiers
6172       for attribute sets.
6173      </para>
6174      <para>
6175       The CQL library of &yaz; defines a <literal>cql_transform_t</literal>
6176       type. It represents a particular mapping between CQL and RPN.
6177       This handle is created and destroyed by the functions:
6178      <synopsis>
6179 cql_transform_t cql_transform_open_FILE (FILE *f);
6180 cql_transform_t cql_transform_open_fname(const char *fname);
6181 void cql_transform_close(cql_transform_t ct);
6182      </synopsis>
6183      The first two functions create a tranformation handle from
6184      either an already open FILE or from a filename respectively.
6185      </para>
6186      <para>
6187       The handle is destroyed by <function>cql_transform_close</function>
6188       in which case no further reference of the handle is allowed.
6189      </para>
6190      <para>
6191       When a <literal>cql_transform_t</literal> handle has been created
6192       you can convert to RPN.
6193       <synopsis>
6194 int cql_transform_buf(cql_transform_t ct,
6195                       struct cql_node *cn, char *out, int max);
6196       </synopsis>
6197       This function converts the CQL tree <literal>cn</literal>
6198       using handle <literal>ct</literal>.
6199       For the resulting PQF, you supply a buffer <literal>out</literal>
6200       which must be able to hold at at least <literal>max</literal>
6201       characters.
6202      </para>
6203      <para>
6204       If conversion failed, <function>cql_transform_buf</function>
6205       returns a non-zero SRU error code; otherwise zero is returned
6206       (conversion successful).  The meanings of the numeric error
6207       codes are listed in the SRU specification somewhere (no
6208       direct link anymore).
6209      </para>
6210      <para>
6211       If conversion fails, more information can be obtained by calling
6212       <synopsis>
6213 int cql_transform_error(cql_transform_t ct, char **addinfop);
6214       </synopsis>
6215       This function returns the most recently returned numeric
6216       error-code and sets the string-pointer at
6217       <literal>*addinfop</literal> to point to a string containing
6218       additional information about the error that occurred: for
6219       example, if the error code is 15 (``Illegal or unsupported context
6220       set''), the additional information is the name of the requested
6221       context set that was not recognised.
6222      </para>
6223      <para>
6224       The SRU error-codes may be translated into brief human-readable
6225       error messages using
6226       <synopsis>
6227 const char *cql_strerror(int code);
6228       </synopsis>
6229      </para>
6230      <para>
6231       If you wish to be able to produce a PQF result in a different
6232       way, there are two alternatives.
6233       <synopsis>
6234 void cql_transform_pr(cql_transform_t ct,
6235                       struct cql_node *cn,
6236                       void (*pr)(const char *buf, void *client_data),
6237                       void *client_data);
6238
6239 int cql_transform_FILE(cql_transform_t ct,
6240                        struct cql_node *cn, FILE *f);
6241       </synopsis>
6242       The former function produces output to a user-defined
6243       output stream. The latter writes the result to an already
6244       open <literal>FILE</literal>.
6245      </para>
6246     </sect3>
6247     <sect3 id="cql.to.rpn">
6248      <title>Specification of CQL to RPN mappings</title>
6249      <para>
6250       The file supplied to functions
6251       <function>cql_transform_open_FILE</function>,
6252       <function>cql_transform_open_fname</function> follows
6253       a structure found in many Unix utilities.
6254       It consists of mapping specifications - one per line.
6255       Lines starting with <literal>#</literal> are ignored (comments).
6256      </para>
6257      <para>
6258       Each line is of the form
6259       <literallayout>
6260        <replaceable>CQL pattern</replaceable><literal> = </literal> <replaceable> RPN equivalent</replaceable>
6261       </literallayout>
6262      </para>
6263      <para>
6264       An RPN pattern is a simple attribute list. Each attribute pair
6265       takes the form:
6266       <literallayout>
6267        [<replaceable>set</replaceable>] <replaceable>type</replaceable><literal>=</literal><replaceable>value</replaceable>
6268       </literallayout>
6269       The attribute <replaceable>set</replaceable> is optional.
6270       The <replaceable>type</replaceable> is the attribute type,
6271       <replaceable>value</replaceable> the attribute value.
6272      </para>
6273      <para>
6274       The character <literal>*</literal> (asterisk) has special meaning
6275       when used in the RPN pattern.
6276       Each occurrence of <literal>*</literal> is substituted with the
6277       CQL matching name (index, relation, qualifier etc).
6278       This facility can be used to copy a CQL name verbatim to the RPN result.
6279      </para>
6280      <para>
6281       The following CQL patterns are recognized:
6282       <variablelist>
6283        <varlistentry>
6284         <term>
6285          <literal>index.</literal><replaceable>set</replaceable><literal>.</literal><replaceable>name</replaceable>
6286         </term>
6287         <listitem>
6288          <para>
6289           This pattern is invoked when a CQL index, such as
6290           dc.title is converted. <replaceable>set</replaceable>
6291           and <replaceable>name</replaceable> are the context set and index
6292           name respectively.
6293           Typically, the RPN specifies an equivalent use attribute.
6294          </para>
6295          <para>
6296           For terms not bound by an index the pattern
6297           <literal>index.cql.serverChoice</literal> is used.
6298           Here, the prefix <literal>cql</literal> is defined as
6299           <literal>http://www.loc.gov/zing/cql/cql-indexes/v1.0/</literal>.
6300           If this pattern is not defined, the mapping will fail.
6301          </para>
6302          <para>
6303           The pattern,
6304           <literal>index.</literal><replaceable>set</replaceable><literal>.*</literal>
6305           is used when no other index pattern is matched.
6306          </para>
6307         </listitem>
6308        </varlistentry>
6309        <varlistentry>
6310         <term>
6311          <literal>qualifier.</literal><replaceable>set</replaceable><literal>.</literal><replaceable>name</replaceable>
6312          (DEPRECATED)
6313         </term>
6314         <listitem>
6315          <para>
6316           For backwards compatibility, this is recognised as a synonym of
6317           <literal>index.</literal><replaceable>set</replaceable><literal>.</literal><replaceable>name</replaceable>
6318          </para>
6319         </listitem>
6320        </varlistentry>
6321        <varlistentry>
6322         <term>
6323          <literal>relation.</literal><replaceable>relation</replaceable>
6324         </term>
6325         <listitem>
6326          <para>
6327           This pattern specifies how a CQL relation is mapped to RPN.
6328           <replaceable>pattern</replaceable> is name of relation
6329           operator. Since <literal>=</literal> is used as
6330           separator between CQL pattern and RPN, CQL relations
6331           including <literal>=</literal> cannot be
6332           used directly. To avoid a conflict, the names
6333           <literal>ge</literal>,
6334           <literal>eq</literal>,
6335           <literal>le</literal>,
6336           must be used for CQL operators, greater-than-or-equal,
6337           equal, less-than-or-equal respectively.
6338           The RPN pattern is supposed to include a relation attribute.
6339          </para>
6340          <para>
6341           For terms not bound by a relation, the pattern
6342           <literal>relation.scr</literal> is used. If the pattern
6343           is not defined, the mapping will fail.
6344          </para>
6345          <para>
6346           The special pattern, <literal>relation.*</literal> is used
6347           when no other relation pattern is matched.
6348          </para>
6349         </listitem>
6350        </varlistentry>
6351        <varlistentry>
6352         <term>
6353          <literal>relationModifier.</literal><replaceable>mod</replaceable>
6354         </term>
6355         <listitem>
6356          <para>
6357           This pattern specifies how a CQL relation modifier is mapped to RPN.
6358           The RPN pattern is usually a relation attribute.
6359          </para>
6360         </listitem>
6361        </varlistentry>
6362        <varlistentry>
6363         <term>
6364          <literal>structure.</literal><replaceable>type</replaceable>
6365         </term>
6366         <listitem>
6367          <para>
6368           This pattern specifies how a CQL structure is mapped to RPN.
6369           Note that this CQL pattern is somewhat to similar to
6370           CQL pattern <literal>relation</literal>.
6371           The <replaceable>type</replaceable> is a CQL relation.
6372          </para>
6373          <para>
6374           The pattern, <literal>structure.*</literal> is used
6375           when no other structure pattern is matched.
6376           Usually, the RPN equivalent specifies a structure attribute.
6377          </para>
6378         </listitem>
6379        </varlistentry>
6380        <varlistentry>
6381         <term>
6382          <literal>position.</literal><replaceable>type</replaceable>
6383         </term>
6384         <listitem>
6385          <para>
6386           This pattern specifies how the anchor (position) of
6387           CQL is mapped to RPN.
6388           The <replaceable>type</replaceable> is one
6389           of <literal>first</literal>, <literal>any</literal>,
6390           <literal>last</literal>, <literal>firstAndLast</literal>.
6391          </para>
6392          <para>
6393           The pattern, <literal>position.*</literal> is used
6394           when no other position pattern is matched.
6395          </para>
6396         </listitem>
6397        </varlistentry>
6398        <varlistentry>
6399         <term>
6400          <literal>set.</literal><replaceable>prefix</replaceable>
6401         </term>
6402         <listitem>
6403          <para>
6404           This specification defines a CQL context set for a given prefix.
6405           The value on the right hand side is the URI for the set -
6406           <emphasis>not</emphasis> RPN. All prefixes used in
6407           index patterns must be defined this way.
6408          </para>
6409         </listitem>
6410        </varlistentry>
6411        <varlistentry>
6412         <term>
6413          <literal>set</literal>
6414         </term>
6415         <listitem>
6416          <para>
6417           This specification defines a default CQL context set for index names.
6418           The value on the right hand side is the URI for the set.
6419          </para>
6420         </listitem>
6421        </varlistentry>
6422       </variablelist>
6423      </para>
6424      <example id="example.cql.to.rpn.mapping">
6425       <title>CQL to RPN mapping file</title>
6426       <para>
6427        This simple file defines two context sets, three indexes and three
6428        relations, a position pattern and a default structure.
6429       </para>
6430       <programlisting><![CDATA[
6431        set.cql  = http://www.loc.gov/zing/cql/context-sets/cql/v1.1/
6432        set.dc   = http://www.loc.gov/zing/cql/dc-indexes/v1.0/
6433
6434        index.cql.serverChoice = 1=1016
6435        index.dc.title         = 1=4
6436        index.dc.subject       = 1=21
6437
6438        relation.<             = 2=1
6439        relation.eq            = 2=3
6440        relation.scr           = 2=3
6441
6442        position.any           = 3=3 6=1
6443
6444        structure.*            = 4=1
6445 ]]>
6446       </programlisting>
6447       <para>
6448        With the mappings above, the CQL query
6449        <screen>
6450         computer
6451        </screen>
6452        is converted to the PQF:
6453        <screen>
6454         @attr 1=1016 @attr 2=3 @attr 4=1 @attr 3=3 @attr 6=1 "computer"
6455        </screen>
6456        by rules <literal>index.cql.serverChoice</literal>,
6457        <literal>relation.scr</literal>, <literal>structure.*</literal>,
6458        <literal>position.any</literal>.
6459       </para>
6460       <para>
6461        CQL query
6462        <screen>
6463         computer^
6464        </screen>
6465        is rejected, since <literal>position.right</literal> is
6466        undefined.
6467       </para>
6468       <para>
6469        CQL query
6470        <screen>
6471         >my = "http://www.loc.gov/zing/cql/dc-indexes/v1.0/" my.title = x
6472        </screen>
6473        is converted to
6474        <screen>
6475         @attr 1=4 @attr 2=3 @attr 4=1 @attr 3=3 @attr 6=1 "x"
6476        </screen>
6477       </para>
6478      </example>
6479      <example id="example.cql.to.rpn.string">
6480       <title>CQL to RPN string attributes</title>
6481       <para>
6482        In this example we allow any index to be passed to RPN as
6483        a use attribute.
6484       </para>
6485       <programlisting><![CDATA[
6486        # Identifiers for prefixes used in this file. (index.*)
6487        set.cql  = info:srw/cql-context-set/1/cql-v1.1
6488        set.rpn  = http://bogus/rpn
6489        set      = http://bogus/rpn
6490
6491        # The default index when none is specified by the query
6492        index.cql.serverChoice     = 1=any
6493
6494        index.rpn.*                = 1=*
6495        relation.eq                = 2=3
6496        structure.*                = 4=1
6497        position.any               = 3=3
6498 ]]>
6499       </programlisting>
6500       <para>
6501        The <literal>http://bogus/rpn</literal> context set is also the default
6502        so we can make queries such as
6503        <screen>
6504         title = a
6505        </screen>
6506        which is converted to
6507        <screen>
6508         @attr 2=3 @attr 4=1 @attr 3=3 @attr 1=title "a"
6509        </screen>
6510       </para>
6511      </example>
6512      <example id="example.cql.to.rpn.bathprofile">
6513       <title>CQL to RPN using Bath Profile</title>
6514       <para>
6515        The file <filename>etc/pqf.properties</filename> has mappings from
6516        the Bath Profile and Dublin Core to RPN.
6517        If YAZ is installed as a package it's usually located
6518        in <filename>/usr/share/yaz/etc</filename> and part of the
6519        development package, such as <literal>libyaz-dev</literal>.
6520       </para>
6521      </example>
6522     </sect3>
6523     <sect3 id="cql.xcql">
6524      <title>CQL to XCQL conversion</title>
6525      <para>
6526       Conversion from CQL to XCQL is trivial and does not
6527       require a mapping to be defined.
6528       There three functions to choose from depending on the
6529       way you wish to store the resulting output (XML buffer
6530       containing XCQL).
6531       <synopsis>
6532 int cql_to_xml_buf(struct cql_node *cn, char *out, int max);
6533 void cql_to_xml(struct cql_node *cn,
6534                 void (*pr)(const char *buf, void *client_data),
6535                 void *client_data);
6536 void cql_to_xml_stdio(struct cql_node *cn, FILE *f);
6537       </synopsis>
6538       Function <function>cql_to_xml_buf</function> converts
6539       to XCQL and stores result in a user supplied buffer of a given
6540       max size.
6541      </para>
6542      <para>
6543       <function>cql_to_xml</function> writes the result in
6544       a user defined output stream.
6545       <function>cql_to_xml_stdio</function> writes to a
6546       a file.
6547      </para>
6548     </sect3>
6549     <sect3 id="rpn.to.cql">
6550      <title>PQF to CQL conversion</title>
6551      <para>
6552       Conversion from PQF to CQL is offered by the two functions shown
6553       below. The former uses a generic stream for result. The latter
6554       puts result in a WRBUF (string container).
6555       <synopsis>
6556 #include &lt;yaz/rpn2cql.h>
6557
6558 int cql_transform_rpn2cql_stream(cql_transform_t ct,
6559                                  void (*pr)(const char *buf, void *client_data),
6560                                  void *client_data,
6561                                  Z_RPNQuery *q);
6562
6563 int cql_transform_rpn2cql_wrbuf(cql_transform_t ct,
6564                                 WRBUF w,
6565                                 Z_RPNQuery *q);
6566       </synopsis>
6567       The configuration is the same as used in CQL to PQF conversions.
6568      </para>
6569     </sect3>
6570    </sect2>
6571   </sect1>
6572   <sect1 id="tools.oid">
6573    <title>Object Identifiers</title>
6574    <para>
6575     The basic YAZ representation of an OID is an array of integers,
6576     terminated with the value -1. This integer is of type
6577     <literal>Odr_oid</literal>.
6578    </para>
6579    <para>
6580     Fundamental OID operations and the type <literal>Odr_oid</literal>
6581     are defined in <filename>yaz/oid_util.h</filename>.
6582    </para>
6583    <para>
6584     An OID can either be declared as a automatic variable or it can
6585     allocated using the memory utilities or ODR/NMEM. It's
6586     guaranteed that an OID can fit in <literal>OID_SIZE</literal> integers.
6587    </para>
6588    <example id="tools.oid.bib1.1"><title>Create OID on stack</title>
6589     <para>
6590      We can create an OID for the Bib-1 attribute set with:
6591      <screen>
6592       Odr_oid bib1[OID_SIZE];
6593       bib1[0] = 1;
6594       bib1[1] = 2;
6595       bib1[2] = 840;
6596       bib1[3] = 10003;
6597       bib1[4] = 3;
6598       bib1[5] = 1;
6599       bib1[6] = -1;
6600      </screen>
6601     </para>
6602    </example>
6603    <para>
6604     And OID may also be filled from a string-based representation using
6605     dots (.). This is achieved by function
6606     <screen>
6607      int oid_dotstring_to_oid(const char *name, Odr_oid *oid);
6608     </screen>
6609     This functions returns 0 if name could be converted; -1 otherwise.
6610    </para>
6611    <example id="tools.oid.bib1.2"><title>Using oid_oiddotstring_to_oid</title>
6612     <para>
6613      We can fill the Bib-1 attribute set OID easier with:
6614      <screen>
6615       Odr_oid bib1[OID_SIZE];
6616       oid_oiddotstring_to_oid("1.2.840.10003.3.1", bib1);
6617      </screen>
6618    </para>
6619    </example>
6620    <para>
6621     We can also allocate an OID dynamically on a ODR stream with:
6622     <screen>
6623     Odr_oid *odr_getoidbystr(ODR o, const char *str);
6624     </screen>
6625     This creates an OID from string-based representation using dots.
6626     This function take an &odr; stream as parameter. This stream is used to
6627     allocate memory for the data elements, which is released on a
6628     subsequent call to <function>odr_reset()</function> on that stream.
6629    </para>
6630    <example id="tools.oid.bib1.3">
6631     <title>Using odr_getoidbystr</title>
6632     <para>
6633      We can create a OID for the Bib-1 attribute set with:
6634      <screen>
6635       Odr_oid *bib1 = odr_getoidbystr(odr, "1.2.840.10003.3.1");
6636      </screen>
6637     </para>
6638    </example>
6639    <para>
6640     The function
6641     <screen>
6642      char *oid_oid_to_dotstring(const Odr_oid *oid, char *oidbuf)
6643     </screen>
6644     does the reverse of <function>oid_oiddotstring_to_oid</function>. It
6645     converts an OID to the string-based representation using dots.
6646     The supplied char buffer <literal>oidbuf</literal> holds the resulting
6647     string and must be at least <literal>OID_STR_MAX</literal> in size.
6648    </para>
6649    <para>
6650     OIDs can be copied with <function>oid_oidcpy</function> which takes
6651     two OID lists as arguments. Alternativly, an OID copy can be allocated
6652     on a ODR stream with:
6653     <screen>
6654      Odr_oid *odr_oiddup(ODR odr, const Odr_oid *o);
6655     </screen>
6656    </para>
6657    <para>
6658     OIDs can be compared with <function>oid_oidcmp</function> which returns
6659     zero if the two OIDs provided are identical; non-zero otherwise.
6660    </para>
6661    <sect2 id="tools.oid.database">
6662     <title>OID database</title>
6663     <para>
6664      From YAZ version 3 and later, the oident system has been replaced
6665      by an OID database. OID database is a misnomer .. the old odient
6666      system was also a database.
6667     </para>
6668     <para>
6669      The OID database is really just a map between named Object Identifiers
6670      (string) and their OID raw equivalents. Most operations either
6671      convert from string to OID or other way around.
6672     </para>
6673     <para>
6674      Unfortunately, whenever we supply a string we must also specify the
6675      <emphasis>OID class</emphasis>. The class is necessary because some
6676      strings correspond to multiple OIDs. An example of such a string is
6677      <literal>Bib-1</literal> which may either be an attribute-set
6678      or a diagnostic-set.
6679     </para>
6680     <para>
6681      Applications using the YAZ database should include
6682      <filename>yaz/oid_db.h</filename>.
6683     </para>
6684     <para>
6685      A YAZ database handle is of type <literal>yaz_oid_db_t</literal>.
6686      Actually that's a pointer. You need not think deal with that.
6687      YAZ has a built-in database which can be considered "constant" for
6688      most purposes.
6689      We can get hold that by using function <function>yaz_oid_std</function>.
6690     </para>
6691     <para>
6692      All functions with prefix <function>yaz_string_to_oid</function>
6693      converts from class + string to OID. We have variants of this
6694      operation due to different memory allocation strategies.
6695     </para>
6696     <para>
6697      All functions with prefix
6698      <function>yaz_oid_to_string</function> converts from OID to string
6699      + class.
6700     </para>
6701     <example id="tools.oid.bib1.4">
6702      <title>Create OID with YAZ DB</title>
6703      <para>
6704       We can create an OID for the Bib-1 attribute set on the ODR stream
6705       odr with:
6706       <screen>
6707         Odr_oid *bib1 =
6708         yaz_string_to_oid_odr(yaz_oid_std(), CLASS_ATTSET, "Bib-1", odr);
6709       </screen>
6710       This is more complex than using <function>odr_getoidbystr</function>.
6711       You would only use <function>yaz_string_to_oid_odr</function> when the
6712       string (here Bib-1) is supplied by a user or configuration.
6713      </para>
6714     </example>
6715    </sect2>
6716    <sect2 id="tools.oid.std">
6717     <title>Standard OIDs</title>
6718     <para>
6719      All the object identifers in the standard OID database as returned
6720      by <function>yaz_oid_std</function> can referenced directly in a
6721      program as a constant OID.
6722      Each constant OID is prefixed with <literal>yaz_oid_</literal> -
6723      followed by OID class (lowercase) - then by OID name (normalized and
6724      lowercase).
6725     </para>
6726     <para>
6727      See <xref linkend="list-oids"/> for list of all object identifiers
6728      built into YAZ.
6729      These are declared in <filename>yaz/oid_std.h</filename> but are
6730      included by <filename>yaz/oid_db.h</filename> as well.
6731     </para>
6732     <example id="tools.oid.bib1.5">
6733      <title>Use a built-in OID</title>
6734      <para>
6735       We can allocate our own OID filled with the constant OID for
6736       Bib-1 with:
6737       <screen>
6738        Odr_oid *bib1 = odr_oiddup(o, yaz_oid_attset_bib1);
6739       </screen>
6740      </para>
6741     </example>
6742    </sect2>
6743   </sect1>
6744   <sect1 id="tools.nmem">
6745    <title>Nibble Memory</title>
6746    <para>
6747     Sometimes when you need to allocate and construct a large,
6748     interconnected complex of structures, it can be a bit of a pain to
6749     release the associated memory again. For the structures describing the
6750     Z39.50 PDUs and related structures, it is convenient to use the
6751     memory-management system of the &odr; subsystem (see
6752     <xref linkend="odr.use"/>). However, in some circumstances
6753     where you might otherwise benefit from using a simple nibble memory
6754     management system, it may be impractical to use
6755     <function>odr_malloc()</function> and <function>odr_reset()</function>.
6756     For this purpose, the memory manager which also supports the &odr;
6757     streams is made available in the NMEM module. The external interface
6758     to this module is given in the <filename>nmem.h</filename> file.
6759    </para>
6760    <para>
6761     The following prototypes are given:
6762    </para>
6763    <screen>
6764     NMEM nmem_create(void);
6765     void nmem_destroy(NMEM n);
6766     void *nmem_malloc(NMEM n, size_t size);
6767     void nmem_reset(NMEM n);
6768     size_t nmem_total(NMEM n);
6769     void nmem_init(void);
6770     void nmem_exit(void);
6771    </screen>
6772    <para>
6773     The <function>nmem_create()</function> function returns a pointer to a
6774     memory control handle, which can be released again by
6775     <function>nmem_destroy()</function> when no longer needed.
6776     The function <function>nmem_malloc()</function> allocates a block of
6777     memory of the requested size. A call to <function>nmem_reset()</function>
6778     or <function>nmem_destroy()</function> will release all memory allocated
6779     on the handle since it was created (or since the last call to
6780     <function>nmem_reset()</function>. The function
6781     <function>nmem_total()</function> returns the number of bytes currently
6782     allocated on the handle.
6783    </para>
6784    <para>
6785     The nibble memory pool is shared amongst threads. POSIX
6786     mutex'es and WIN32 Critical sections are introduced to keep the
6787     module thread safe. Function <function>nmem_init()</function>
6788     initializes the nibble memory library and it is called automatically
6789     the first time the <literal>YAZ.DLL</literal> is loaded. &yaz; uses
6790     function <function>DllMain</function> to achieve this. You should
6791     <emphasis>not</emphasis> call <function>nmem_init</function> or
6792     <function>nmem_exit</function> unless you're absolute sure what
6793     you're doing. Note that in previous &yaz; versions you'd have to call
6794     <function>nmem_init</function> yourself.
6795    </para>
6796   </sect1>
6797   <sect1 id="tools.log">
6798    <title>Log</title>
6799    <para>
6800     &yaz; has evolved a fairly complex log system which should be useful both
6801     for debugging &yaz; itself, debugging applications that use &yaz;, and for
6802     production use of those applications.
6803    </para>
6804    <para>
6805     The log functions are declared in header <filename>yaz/log.h</filename>
6806     and implemented in <filename>src/log.c</filename>.
6807     Due to name clash with syslog and some math utilities the logging
6808     interface has been modified as of YAZ 2.0.29. The obsolete interface
6809     is still available if in header file <filename>yaz/log.h</filename>.
6810     The key points of the interface are:
6811    </para>
6812    <screen>
6813     void yaz_log(int level, const char *fmt, ...)
6814     void yaz_log_init(int level, const char *prefix, const char *name);
6815     void yaz_log_init_file(const char *fname);
6816     void yaz_log_init_level(int level);
6817     void yaz_log_init_prefix(const char *prefix);
6818     void yaz_log_time_format(const char *fmt);
6819     void yaz_log_init_max_size(int mx);
6820
6821     int yaz_log_mask_str(const char *str);
6822     int yaz_log_module_level(const char *name);
6823    </screen>
6824    <para>
6825     The reason for the whole log module is the <function>yaz_log</function>
6826     function. It takes a bitmask indicating the log levels, a
6827     <literal>printf</literal>-like format string, and a variable number of
6828     arguments to log.
6829    </para>
6830    <para>
6831     The <literal>log level</literal> is a bit mask, that says on which level(s)
6832     the log entry should be made, and optionally set some behaviour of the
6833     logging. In the most simple cases, it can be one of <literal>YLOG_FATAL,
6834     YLOG_DEBUG, YLOG_WARN, YLOG_LOG</literal>. Those can be combined with bits
6835     that modify the way the log entry is written:<literal>YLOG_ERRNO,
6836     YLOG_NOTIME, YLOG_FLUSH</literal>.
6837     Most of the rest of the bits are deprecated, and should not be used. Use
6838     the dynamic log levels instead.
6839    </para>
6840    <para>
6841     Applications that use &yaz;, should not use the LOG_LOG for ordinary
6842     messages, but should make use of the dynamic loglevel system. This consists
6843     of two parts, defining the loglevel and checking it.
6844    </para>
6845    <para>
6846     To define the log levels, the (main) program should pass a string to
6847     <function>yaz_log_mask_str</function> to define which log levels are to be
6848     logged. This string should be a comma-separated list of log level names,
6849     and can contain both hard-coded names and dynamic ones. The log level
6850     calculation starts with <literal>YLOG_DEFAULT_LEVEL</literal> and adds a bit
6851     for each word it meets, unless the word starts with a '-', in which case it
6852     clears the bit. If the string <literal>'none'</literal> is found,
6853     all bits are cleared. Typically this string comes from the command-line,
6854     often identified by <literal>-v</literal>. The
6855     <function>yaz_log_mask_str</function> returns a log level that should be
6856     passed to <function>yaz_log_init_level</function> for it to take effect.
6857    </para>
6858    <para>
6859     Each module should check what log bits it should be used, by calling
6860     <function>yaz_log_module_level</function> with a suitable name for the
6861     module. The name is cleared from a preceding path and an extension, if any,
6862     so it is quite possible to use <literal>__FILE__</literal> for it. If the
6863     name has been passed to <function>yaz_log_mask_str</function>, the routine
6864     returns a non-zero bitmask, which should then be used in consequent calls
6865     to yaz_log. (It can also be tested, so as to avoid unnecessary calls to
6866     yaz_log, in time-critical places, or when the log entry would take time
6867     to construct.)
6868    </para>
6869    <para>
6870     Yaz uses the following dynamic log levels:
6871     <literal>server, session, request, requestdetail</literal> for the server
6872     functionality.
6873     <literal>zoom</literal> for the zoom client api.
6874     <literal>ztest</literal> for the simple test server.
6875     <literal>malloc, nmem, odr, eventl</literal> for internal
6876     debugging of yaz itself.
6877     Of course, any program using yaz is welcome to define as many new
6878     ones, as it needs.
6879    </para>
6880    <para>
6881     By default the log is written to stderr, but this can be changed by a call
6882     to <function>yaz_log_init_file</function> or
6883     <function>yaz_log_init</function>. If the log is directed to a file, the
6884     file size is checked at every write, and if it exceeds the limit given in
6885     <function>yaz_log_init_max_size</function>, the log is rotated. The
6886     rotation keeps one old version (with a <literal>.1</literal> appended to
6887     the name). The size defaults to 1GB. Setting it to zero will disable the
6888     rotation feature.
6889    </para>
6890    <screen>
6891     A typical yaz-log looks like this
6892   13:23:14-23/11 yaz-ztest(1) [session] Starting session from tcp:127.0.0.1 (pid=30968)
6893   13:23:14-23/11 yaz-ztest(1) [request] Init from 'YAZ' (81) (ver 2.0.28) OK
6894   13:23:17-23/11 yaz-ztest(1) [request] Search Z: @attrset Bib-1 foo  OK:7 hits
6895   13:23:22-23/11 yaz-ztest(1) [request] Present: [1] 2+2  OK 2 records returned
6896   13:24:13-23/11 yaz-ztest(1) [request] Close OK
6897    </screen>
6898    <para>
6899     The log entries start with a time stamp. This can be omitted by setting the
6900     <literal>YLOG_NOTIME</literal> bit in the loglevel. This way automatic tests
6901     can be hoped to produce identical log files, that are easy to diff. The
6902     format of the time stamp can be set with
6903     <function>yaz_log_time_format</function>, which takes a format string just
6904     like <function>strftime</function>.
6905    </para>
6906    <para>
6907     Next in a log line comes the prefix, often the name of the program. For
6908     yaz-based servers, it can also contain the session number. Then
6909     comes one or more logbits in square brackets, depending on the logging
6910     level set by <function>yaz_log_init_level</function> and the loglevel
6911     passed to <function>yaz_log_init_level</function>. Finally comes the format
6912     string and additional values passed to <function>yaz_log</function>
6913    </para>
6914    <para>
6915     The log level <literal>YLOG_LOGLVL</literal>, enabled by the string
6916     <literal>loglevel</literal>, will log all the log-level affecting
6917     operations. This can come in handy if you need to know what other log
6918     levels would be useful. Grep the logfile for <literal>[loglevel]</literal>.
6919    </para>
6920    <para>
6921     The log system is almost independent of the rest of &yaz;, the only
6922     important dependence is of <filename>nmem</filename>, and that only for
6923     using the semaphore definition there.
6924    </para>
6925    <para>
6926     The dynamic log levels and log rotation were introduced in &yaz; 2.0.28. At
6927     the same time, the log bit names were changed from
6928     <literal>LOG_something</literal> to <literal>YLOG_something</literal>,
6929     to avoid collision with <filename>syslog.h</filename>.
6930    </para>
6931   </sect1>
6932   <sect1 id="marc">
6933    <title>MARC</title>
6934    <para>
6935     YAZ provides a fast utility for working with MARC records.
6936     Early versions of the MARC utility only allowed decoding of ISO2709.
6937     Today the utility may both encode - and decode to a varity of formats.
6938    </para>
6939    <synopsis><![CDATA[
6940     #include <yaz/marcdisp.h>
6941
6942     /* create handler */
6943     yaz_marc_t yaz_marc_create(void);
6944     /* destroy */
6945     void yaz_marc_destroy(yaz_marc_t mt);
6946
6947     /* set XML mode YAZ_MARC_LINE, YAZ_MARC_SIMPLEXML, ... */
6948     void yaz_marc_xml(yaz_marc_t mt, int xmlmode);
6949     #define YAZ_MARC_LINE      0
6950     #define YAZ_MARC_SIMPLEXML 1
6951     #define YAZ_MARC_OAIMARC   2
6952     #define YAZ_MARC_MARCXML   3
6953     #define YAZ_MARC_ISO2709   4
6954     #define YAZ_MARC_XCHANGE   5
6955     #define YAZ_MARC_CHECK     6
6956     #define YAZ_MARC_TURBOMARC 7
6957     #define YAZ_MARC_JSON      8
6958
6959     /* supply iconv handle for character set conversion .. */
6960     void yaz_marc_iconv(yaz_marc_t mt, yaz_iconv_t cd);
6961
6962     /* set debug level, 0=none, 1=more, 2=even more, .. */
6963     void yaz_marc_debug(yaz_marc_t mt, int level);
6964
6965     /* decode MARC in buf of size bsize. Returns >0 on success; <=0 on failure.
6966     On success, result in *result with size *rsize. */
6967     int yaz_marc_decode_buf(yaz_marc_t mt, const char *buf, int bsize,
6968                             const char **result, size_t *rsize);
6969
6970     /* decode MARC in buf of size bsize. Returns >0 on success; <=0 on failure.
6971        On success, result in WRBUF */
6972     int yaz_marc_decode_wrbuf(yaz_marc_t mt, const char *buf,
6973                               int bsize, WRBUF wrbuf);
6974 ]]>
6975    </synopsis>
6976    <note>
6977     <para>
6978      The synopsis is just a basic subset of all functionality. Refer
6979      to the actual header file <filename>marcdisp.h</filename> for
6980      details.
6981     </para>
6982    </note>
6983    <para>
6984     A MARC conversion handle must be created by using
6985     <function>yaz_marc_create</function> and destroyed
6986     by calling <function>yaz_marc_destroy</function>.
6987    </para>
6988    <para>
6989     All other function operate on a <literal>yaz_marc_t</literal> handle.
6990     The output is specified by a call to <function>yaz_marc_xml</function>.
6991     The <literal>xmlmode</literal> must be one of
6992     <variablelist>
6993      <varlistentry>
6994       <term>YAZ_MARC_LINE</term>
6995       <listitem>
6996        <para>
6997         A simple line-by-line format suitable for display but not
6998         recommend for further (machine) processing.
6999        </para>
7000       </listitem>
7001      </varlistentry>
7002      <varlistentry>
7003       <term>YAZ_MARC_MARCXML</term>
7004       <listitem>
7005        <para>
7006         <ulink url="&url.marcxml;">MARCXML</ulink>.
7007        </para>
7008       </listitem>
7009      </varlistentry>
7010      <varlistentry>
7011       <term>YAZ_MARC_ISO2709</term>
7012       <listitem>
7013        <para>
7014         ISO2709 (sometimes just referred to as "MARC").
7015        </para>
7016       </listitem>
7017      </varlistentry>
7018      <varlistentry>
7019       <term>YAZ_MARC_XCHANGE</term>
7020       <listitem>
7021        <para>
7022         <ulink url="&url.marcxchange;">MarcXchange</ulink>.
7023        </para>
7024       </listitem>
7025      </varlistentry>
7026      <varlistentry>
7027       <term>YAZ_MARC_CHECK</term>
7028       <listitem>
7029        <para>
7030         Pseudo format for validation only. Does not generate
7031         any real output except diagnostics.
7032        </para>
7033       </listitem>
7034      </varlistentry>
7035      <varlistentry>
7036       <term>YAZ_MARC_TURBOMARC</term>
7037       <listitem>
7038        <para>
7039         XML format with same semantics as MARCXML but more compact
7040         and geared towards fast processing with XSLT. Refer to
7041         <xref linkend="tools.turbomarc"/> for more information.
7042        </para>
7043       </listitem>
7044      </varlistentry>
7045      <varlistentry>
7046       <term>YAZ_MARC_JSON</term>
7047       <listitem>
7048        <para>
7049         <ulink url="&url.marc_in_json;">MARC-in_JSON</ulink> format.
7050        </para>
7051       </listitem>
7052      </varlistentry>
7053     </variablelist>
7054    </para>
7055    <para>
7056     The actual conversion functions are
7057     <function>yaz_marc_decode_buf</function> and
7058     <function>yaz_marc_decode_wrbuf</function> which decodes and encodes
7059     a MARC record. The former function operates on simple buffers, the
7060     stores the resulting record in a WRBUF handle (WRBUF is a simple string
7061     type).
7062    </para>
7063    <example id="example.marc.display">
7064     <title>Display of MARC record</title>
7065     <para>
7066      The following program snippet illustrates how the MARC API may
7067      be used to convert a MARC record to the line-by-line format:
7068      <programlisting><![CDATA[
7069       void print_marc(const char *marc_buf, int marc_buf_size)
7070       {
7071          char *result;      /* for result buf */
7072          size_t result_len;    /* for size of result */
7073          yaz_marc_t mt = yaz_marc_create();
7074          yaz_marc_xml(mt, YAZ_MARC_LINE);
7075          yaz_marc_decode_buf(mt, marc_buf, marc_buf_size,
7076                              &result, &result_len);
7077          fwrite(result, result_len, 1, stdout);
7078          yaz_marc_destroy(mt);  /* note that result is now freed... */
7079       }
7080 ]]>
7081      </programlisting>
7082     </para>
7083    </example>
7084    <sect2 id="tools.turbomarc">
7085     <title>TurboMARC</title>
7086     <para>
7087      TurboMARC is yet another XML encoding of a MARC record. The format
7088      was designed for fast processing with XSLT.
7089     </para>
7090     <para>
7091      Applications like
7092      Pazpar2 uses XSLT to convert an XML encoded MARC record to an internal
7093      representation. This conversion mostly check the tag of a MARC field
7094      to determine the basic rules in the conversion. This check is
7095      costly when that is tag is encoded as an attribute in MARCXML.
7096      By having the tag value as the element instead, makes processing
7097      many times faster (at least for Libxslt).
7098     </para>
7099     <para>
7100      TurboMARC is encoded as follows:
7101      <itemizedlist>
7102       <listitem>
7103        <para>
7104         Record elements is part of namespace
7105         "<literal>http://www.indexdata.com/turbomarc</literal>".
7106       </para>
7107       </listitem>
7108       <listitem>
7109        <para>
7110         A record is enclosed in element <literal>r</literal>.
7111       </para>
7112       </listitem>
7113       <listitem>
7114        <para>
7115         A collection of records is enclosed in element
7116         <literal>collection</literal>.
7117        </para>
7118       </listitem>
7119       <listitem>
7120        <para>
7121         The leader is encoded as element <literal>l</literal> with the
7122         leader content as its (text) value.
7123       </para>
7124       </listitem>
7125       <listitem>
7126        <para>
7127         A control field is encoded as element <literal>c</literal> concatenated
7128         with the tag value of the control field if the tag value
7129         matches the regular expression <literal>[a-zA-Z0-9]*</literal>.
7130         If the tag value do not match the regular expression
7131         <literal>[a-zA-Z0-9]*</literal> the control field is encoded
7132         as element <literal>c</literal> and attribute <literal>code</literal>
7133         will hold the tag value.
7134         This rule ensure that in the rare cases where a tag value might
7135         result in a non-wellformed XML YAZ encode it as a coded attribute
7136         (as in MARCXML).
7137        </para>
7138        <para>
7139         The control field content is the the text value of this element.
7140         Indicators are encoded as attribute names
7141         <literal>i1</literal>, <literal>i2</literal>, etc.. and
7142         corresponding values for each indicator.
7143        </para>
7144       </listitem>
7145       <listitem>
7146        <para>
7147         A data field is encoded as element <literal>d</literal> concatenated
7148         with the tag value of the data field or using the attribute
7149         <literal>code</literal> as described in the rules for control fields.
7150         The children of the data field element is subfield elements.
7151         Each subfield element is encoded as <literal>s</literal>
7152         concatenated with the sub field code.
7153         The text of the subfield element is the contents of the subfield.
7154         Indicators are encoded as attributes for the data field element similar
7155         to the encoding for control fields.
7156       </para>
7157       </listitem>
7158      </itemizedlist>
7159     </para>
7160    </sect2>
7161   </sect1>
7162   <sect1 id="tools.retrieval">
7163    <title>Retrieval Facility</title>
7164    <para>
7165     YAZ version 2.1.20 or later includes a Retrieval facility tool
7166     which allows a SRU/Z39.50 to describe itself and perform record
7167     conversions. The idea is the following:
7168     <itemizedlist>
7169      <listitem>
7170       <para>
7171        An SRU/Z39.50 client sends a retrieval request which includes
7172        a combination of the following parameters: syntax (format),
7173        schema (or element set name).
7174       </para>
7175      </listitem>
7176      <listitem>
7177       <para>
7178        The retrieval facility is invoked with parameters in a
7179        server/proxy. The retrieval facility matches the parameters a set of
7180        "supported" retrieval types.
7181        If there is no match, the retrieval signals an error
7182        (syntax and / or schema not supported).
7183       </para>
7184      </listitem>
7185      <listitem>
7186       <para>
7187        For a successful match, the backend is invoked with the same
7188        or altered retrieval parameters (syntax, schema). If
7189        a record is received from the backend, it is converted to the
7190        frontend name / syntax.
7191       </para>
7192      </listitem>
7193      <listitem>
7194       <para>
7195        The resulting record is sent back the client and tagged with
7196        the frontend syntax / schema.
7197       </para>
7198      </listitem>
7199     </itemizedlist>
7200    </para>
7201    <para>
7202     The Retrieval facility is driven by an XML configuration. The
7203     configuration is neither Z39.50 ZeeRex or SRU ZeeRex. But it
7204     should be easy to generate both of them from the XML configuration.
7205     (unfortunately the two versions
7206     of ZeeRex differ substantially in this regard).
7207    </para>
7208    <sect2 id="tools.retrieval.format">
7209     <title>Retrieval XML format</title>
7210     <para>
7211      All elements should be covered by namespace
7212      <literal>http://indexdata.com/yaz</literal> .
7213      The root element node must be <literal>retrievalinfo</literal>.
7214     </para>
7215     <para>
7216      The <literal>retrievalinfo</literal> must include one or
7217      more <literal>retrieval</literal> elements. Each
7218     <literal>retrieval</literal> defines specific combination of
7219      syntax, name and identifier supported by this retrieval service.
7220     </para>
7221     <para>
7222      The <literal>retrieval</literal> element may include any of the
7223      following attributes:
7224      <variablelist>
7225       <varlistentry><term><literal>syntax</literal> (REQUIRED)</term>
7226        <listitem>
7227         <para>
7228          Defines the record syntax. Possible values is any
7229          of the names defined in YAZ' OID database or a raw
7230          OID in (n.n ... n).
7231         </para>
7232        </listitem>
7233       </varlistentry>
7234       <varlistentry><term><literal>name</literal> (OPTIONAL)</term>
7235        <listitem>
7236         <para>
7237          Defines the name of the retrieval format. This can be
7238          any string. For SRU, the value, is equivalent to schema (short-hand);
7239          for Z39.50 it's equivalent to simple element set name.
7240          For YAZ 3.0.24 and later this name may be specified as a glob
7241          expression with operators
7242          <literal>*</literal> and <literal>?</literal>.
7243         </para>
7244        </listitem>
7245       </varlistentry>
7246       <varlistentry><term><literal>identifier</literal> (OPTIONAL)</term>
7247        <listitem>
7248         <para>
7249          Defines the URI schema name of the retrieval format. This can be
7250          any string. For SRU, the value, is equivalent to URI schema.
7251          For Z39.50, there is no equivalent.
7252         </para>
7253        </listitem>
7254       </varlistentry>
7255      </variablelist>
7256     </para>
7257     <para>
7258      The <literal>retrieval</literal> may include one
7259      <literal>backend</literal> element. If a <literal>backend</literal>
7260      element is given, it specifies how the records are retrieved by
7261      some backend and how the records are converted from the backend to
7262      the "frontend".
7263     </para>
7264     <para>
7265      The attributes, <literal>name</literal> and <literal>syntax</literal>
7266      may be specified for the <literal>backend</literal> element. These
7267      semantics of these attributes is equivalent to those for the
7268      <literal>retrieval</literal>. However, these values are passed to
7269      the "backend".
7270     </para>
7271     <para>
7272      The <literal>backend</literal> element may includes one or more
7273      conversion instructions (as children elements). The supported
7274      conversions are:
7275      <variablelist>
7276       <varlistentry><term><literal>marc</literal></term>
7277        <listitem>
7278         <para>
7279          The <literal>marc</literal> element specifies a conversion
7280          to - and from ISO2709 encoded MARC and
7281          <ulink url="&url.marcxml;">&acro.marcxml;</ulink>/MarcXchange.
7282          The following attributes may be specified:
7283          <variablelist>
7284           <varlistentry>
7285            <term><literal>inputformat</literal> (REQUIRED)</term>
7286            <listitem>
7287             <para>
7288              Format of input. Supported values are
7289              <literal>marc</literal> (for ISO2709), <literal>xml</literal>
7290              (MARCXML/MarcXchange) and <literal>json</literal>
7291              (<ulink url="&url.marc_in_json;">MARC-in_JSON</ulink>).
7292             </para>
7293            </listitem>
7294           </varlistentry>
7295           <varlistentry>
7296            <term><literal>outputformat</literal> (REQUIRED)</term>
7297            <listitem>
7298             <para>
7299              Format of output. Supported values are
7300              <literal>line</literal> (MARC line format);
7301              <literal>marcxml</literal> (for MARCXML),
7302              <literal>marc</literal> (ISO2709),
7303              <literal>marcxhcange</literal> (for MarcXchange),
7304              or <literal>json</literal>
7305              (<ulink url="&url.marc_in_json;">MARC-in_JSON </ulink>).
7306             </para>
7307            </listitem>
7308           </varlistentry>
7309           <varlistentry>
7310            <term><literal>inputcharset</literal> (OPTIONAL)</term>
7311            <listitem>
7312             <para>
7313              Encoding of input. For XML input formats, this need not
7314              be given, but for ISO2709 based inputformats, this should
7315              be set to the encoding used. For MARC21 records, a common
7316              inputcharset value  would be <literal>marc-8</literal>.
7317             </para>
7318            </listitem>
7319           </varlistentry>
7320           <varlistentry>
7321            <term><literal>outputcharset</literal> (OPTIONAL)</term>
7322            <listitem>
7323             <para>
7324              Encoding of output. If outputformat is XML based, it is
7325              strongly recommened to use <literal>utf-8</literal>.
7326             </para>
7327            </listitem>
7328           </varlistentry>
7329          </variablelist>
7330         </para>
7331        </listitem>
7332       </varlistentry>
7333       <varlistentry>
7334        <term><literal>xslt</literal></term>
7335        <listitem>
7336         <para>
7337          The <literal>xslt</literal> element specifies a conversion
7338          via &acro.xslt;. The following attributes may be specified:
7339          <variablelist>
7340           <varlistentry><term><literal>stylesheet</literal> (REQUIRED)</term>
7341            <listitem>
7342             <para>
7343              Stylesheet file.
7344             </para>
7345            </listitem>
7346           </varlistentry>
7347          </variablelist>
7348         </para>
7349        </listitem>
7350       </varlistentry>
7351       <varlistentry>
7352        <term><literal>solrmarc</literal></term>
7353        <listitem>
7354         <para>
7355          The <literal>solrmarc</literal> decodes solrmarc records.
7356          It assumes that the input is pure solrmarc text (no escaping)
7357          and will convert all sequences of the form #XX; to a single
7358          character of the hexadecimal value as given by XX. The output,
7359          presumably, is a valid ISO2709 buffer.
7360         </para>
7361         <para>
7362          This conversion is available in YAZ 5.0.21 and later.
7363         </para>
7364        </listitem>
7365       </varlistentry>
7366      </variablelist>
7367     </para>
7368    </sect2>
7369    <sect2 id="tools.retrieval.examples">
7370     <title>Retrieval Facility Examples</title>
7371     <example id="tools.retrieval.marc21">
7372      <title>MARC21 backend</title>
7373      <para>
7374       A typical way to use the retrieval facility is to enable XML
7375       for servers that only supports ISO2709 encoded MARC21 records.
7376      </para>
7377      <programlisting><![CDATA[
7378      <retrievalinfo>
7379        <retrieval syntax="usmarc" name="F"/>
7380        <retrieval syntax="usmarc" name="B"/>
7381        <retrieval syntax="xml" name="marcxml"
7382                   identifier="info:srw/schema/1/marcxml-v1.1">
7383          <backend syntax="usmarc" name="F">
7384            <marc inputformat="marc" outputformat="marcxml"
7385                  inputcharset="marc-8"/>
7386          </backend>
7387        </retrieval>
7388        <retrieval syntax="xml" name="dc">
7389          <backend syntax="usmarc" name="F">
7390            <marc inputformat="marc" outputformat="marcxml"
7391                  inputcharset="marc-8"/>
7392            <xslt stylesheet="MARC21slim2DC.xsl"/>
7393          </backend>
7394        </retrieval>
7395      </retrievalinfo>
7396 ]]>
7397      </programlisting>
7398      <para>
7399       This means that our frontend supports:
7400       <itemizedlist>
7401        <listitem>
7402         <para>
7403          MARC21 F(ull) records.
7404         </para>
7405        </listitem>
7406        <listitem>
7407         <para>
7408          MARC21 B(rief) records.
7409         </para>
7410        </listitem>
7411        <listitem>
7412         <para>
7413          MARCXML records.
7414         </para>
7415        </listitem>
7416        <listitem>
7417         <para>
7418          Dublin core records.
7419         </para>
7420        </listitem>
7421       </itemizedlist>
7422      </para>
7423     </example>
7424     <example id="tools.retrieval.marcxml">
7425      <title>MARCXML backend</title>
7426      <para>
7427       SRW/SRU and Solr backends returns records in XML.
7428       If they return MARCXML or MarcXchange, the retrieval module
7429       can convert those into ISO2709 formats, most commonly USMARC
7430       (AKA MARC21).
7431       In this example, the backend returns MARCXML for schema="marcxml".
7432      </para>
7433      <programlisting><![CDATA[
7434      <retrievalinfo>
7435        <retrieval syntax="usmarc">
7436          <backend syntax="xml" name="marcxml">
7437            <marc inputformat="xml" outputformat="marc"
7438                  outputcharset="marc-8"/>
7439          </backend>
7440        </retrieval>
7441        <retrieval syntax="xml" name="marcxml"
7442                   identifier="info:srw/schema/1/marcxml-v1.1"/>
7443        <retrieval syntax="xml" name="dc">
7444          <backend syntax="xml" name="marcxml">
7445            <xslt stylesheet="MARC21slim2DC.xsl"/>
7446          </backend>
7447        </retrieval>
7448      </retrievalinfo>
7449 ]]>
7450      </programlisting>
7451      <para>
7452       This means that our frontend supports:
7453       <itemizedlist>
7454        <listitem>
7455         <para>
7456          MARC21 records (any element set name) in MARC-8 encoding.
7457         </para>
7458        </listitem>
7459        <listitem>
7460         <para>
7461          MARCXML records for element-set=marcxml
7462         </para>
7463        </listitem>
7464        <listitem>
7465         <para>
7466          Dublin core records for element-set=dc.
7467         </para>
7468        </listitem>
7469       </itemizedlist>
7470      </para>
7471     </example>
7472    </sect2>
7473    <sect2 id="tools.retrieval.api">
7474     <title>API</title>
7475     <para>
7476      It should be easy to use the retrieval systems from applications. Refer
7477      to the headers
7478      <filename>yaz/retrieval.h</filename> and
7479      <filename>yaz/record_conv.h</filename>.
7480     </para>
7481    </sect2>
7482   </sect1>
7483   <sect1 id="sorting">
7484    <title>Sorting</title>
7485    <para>
7486     This chapter describes sorting and how it is supported in YAZ.
7487     Sorting applies to a result-set.
7488     The
7489     <ulink url="http://www.loc.gov/z3950/agency/markup/05.html#3.2.7">
7490      Z39.50 sorting facility
7491     </ulink>
7492     takes one or more input result-sets
7493     and one result-set as output. The most simple case is that
7494     the input-set is the same as the output-set.
7495    </para>
7496    <para>
7497     Z39.50 sorting has a separate APDU (service) that is, thus, performed
7498     following a search (two phases).
7499    </para>
7500    <para>
7501     In SRU/Solr, however, the model is different. Here, sorting is specified
7502     during the the search operation. Note, however, that SRU might
7503     perform sort as separate search, by referring to an existing result-set
7504     in the query (result-set reference).
7505    </para>
7506    <sect2>
7507     <title>Using the Z39.50 sort service</title>
7508     <para>
7509      yaz-client and the ZOOM API supports the Z39.50 sort facility. In any
7510      case the sort sequence or sort critiera is using a string notation.
7511      This notation is a one-line notation suitable for being manually
7512      entered or generated and allows for easy logging (one liner).
7513      For the ZOOM API, the sort is specified in the call to ZOOM_query_sortby
7514      function. For yaz-client the sort is performed and specified using
7515      the sort and sort+ commands. For description of the sort criteria notation
7516      refer to the <link linkend="sortspec">sort command</link> in the
7517      yaz-client manual.
7518     </para>
7519     <para>
7520      The ZOOM API might choose one of several sort strategies for
7521      sorting. Refer to <xref linkend="zoom-sort-strategy"/>.
7522     </para>
7523    </sect2>
7524    <sect2>
7525     <title>Type-7 sort</title>
7526     <para>
7527      Type-7 sort is an extension to the Bib-1 based RPN query where the
7528      sort specification is embedded as an Attribute-Plus-Term.
7529     </para>
7530     <para>
7531      The objectives for introducing Type-7 sorting is that it allows
7532      a client to perform sorting even if it does not implement/support
7533      Z39.50 sort. Virtually all Z39.50 client software supports
7534      RPN queries. It also may improve performance because the sort
7535      critieria is specified along with the search query.
7536     </para>
7537     <para>
7538      The sort is triggered by the presence of type 7 and the value of type 7
7539      specifies the
7540      <ulink url="http://www.loc.gov/z3950/agency/asn1.html#SortKeySpec">
7541       sortRelation
7542      </ulink>
7543      The value for type 7 is 1 for ascending and 2 for descending.
7544      For the
7545      <ulink url="http://www.loc.gov/z3950/agency/asn1.html#SortElement">
7546       sortElement
7547      </ulink>
7548      only the generic part is handled. If generic sortKey is of type
7549      sortField, then attribute type 1 is present and the value is
7550      sortField (InternationalString). If generic sortKey is of type
7551      sortAttributes, then the attributes in list is used . generic sortKey
7552      of type elementSpec is not supported.
7553     </para>
7554     <para>
7555      The term in the sorting Attribute-Plus-Term combo should hold
7556      an integer. The value is 0 for primary sorting criteria, 1 for second
7557      criteria, etc.
7558     </para>
7559    </sect2>
7560   </sect1>
7561   <sect1 id="facets">
7562    <title>Facets</title>
7563    <para>
7564     YAZ supports facets for in Solr, SRU 2.0 and Z39.50 protocols.
7565    </para>
7566    <para>
7567     Like Type-1/RPN, YAZ supports a string notation for specifying
7568     facets. For the API this is performed by
7569     <function>yaz_pqf_parse_facet_list</function>.
7570    </para>
7571    <para>
7572     For ZOOM C the facets are given by option "facets"
7573     For yaz-client it is used for the facets command.
7574    </para>
7575    <para>
7576     The grammar of this specification is as follows:
7577     <literallayout>
7578    facet-spec ::= facet-list
7579
7580    facet-list ::= facet-list ',' attr-spec | attr-spec
7581
7582    attr-spec ::= attr-spec '@attr' string | '@attr' string
7583
7584     </literallayout>
7585     The notation is inspired by PQF. The string following '@attr'
7586     may not include blanks and is of the form
7587     <replaceable>type</replaceable><literal>=</literal><replaceable>value</replaceable>,
7588     where <replaceable>type</replaceable> is an integer and
7589     <replaceable>value</replaceable> is a string or an integer.
7590    </para>
7591    <para>
7592     The Facets specification is not Bib-1. The following types apply:
7593    </para>
7594    <table id="facet.attributes">
7595     <title>Facet attributes</title>
7596     <tgroup cols="2">
7597      <colspec colwidth="2*" colname="type"></colspec>
7598      <colspec colwidth="9*" colname="description"></colspec>
7599      <thead>
7600       <row>
7601        <entry>Type</entry>
7602        <entry>Description</entry>
7603       </row>
7604      </thead>
7605      <tbody>
7606       <row>
7607        <entry>1</entry>
7608        <entry>
7609         Field-name. This is often a string, eg "Author", "Year", etc.
7610        </entry>
7611       </row>
7612       <row>
7613        <entry>2</entry>
7614        <entry>
7615         Sort order. Value should be an integer.
7616         Value 0: count descending (frequency). Value 1: alpha ascending.
7617        </entry>
7618       </row>
7619       <row>
7620        <entry>3</entry>
7621        <entry>
7622         Number of terms requested.
7623        </entry>
7624       </row>
7625       <row>
7626        <entry>4</entry>
7627        <entry>
7628         Start offset.
7629        </entry>
7630       </row>
7631      </tbody>
7632     </tgroup>
7633    </table>
7634   </sect1>
7635  </chapter>
7636  <chapter id="odr">
7637   <title>The ODR Module</title>
7638   <sect1 id="odr.introduction">
7639    <title>Introduction</title>
7640    <para>
7641     &odr; is the BER-encoding/decoding subsystem of &yaz;. Care as been taken
7642     to isolate &odr; from the rest of the package - specifically from the
7643     transport interface. &odr; may be used in any context where basic
7644     ASN.1/BER representations are used.
7645    </para>
7646    <para>
7647     If you are only interested in writing a Z39.50 implementation based on
7648     the PDUs that are already provided with &yaz;, you only need to concern
7649     yourself with the section on managing ODR streams
7650     (<xref linkend="odr.use"/>). Only if you need to
7651     implement ASN.1 beyond that which has been provided, should you
7652     worry about the second half of the documentation
7653     (<xref linkend="odr.programming"/>).
7654     If you use one of the higher-level interfaces, you can skip this
7655     section entirely.
7656    </para>
7657    <para>
7658     This is important, so we'll repeat it for emphasis: <emphasis>You do
7659     not need to read <xref linkend="odr.programming"/>
7660     to implement Z39.50 with &yaz;.</emphasis>
7661    </para>
7662    <para>
7663     If you need a part of the protocol that isn't already in &yaz;, you
7664     should contact the authors before going to work on it yourself: We
7665     might already be working on it. Conversely, if you implement a useful
7666     part of the protocol before us, we'd be happy to include it in a
7667     future release.
7668    </para>
7669   </sect1>
7670   <sect1 id="odr.use">
7671    <title>Using ODR</title>
7672    <sect2 id="odr.streams">
7673     <title>ODR Streams</title>
7674     <para>
7675      Conceptually, the ODR stream is the source of encoded data in the
7676      decoding mode; when encoding, it is the receptacle for the encoded
7677      data. Before you can use an ODR stream it must be allocated. This is
7678      done with the function
7679     </para>
7680     <synopsis>
7681      ODR odr_createmem(int direction);
7682     </synopsis>
7683     <para>
7684      The <function>odr_createmem()</function> function takes as argument one
7685      of three manifest constants: <literal>ODR_ENCODE</literal>,
7686      <literal>ODR_DECODE</literal>, or <literal>ODR_PRINT</literal>.
7687      An &odr; stream can be in only one mode - it is not possible to change
7688      its mode once it's selected. Typically, your program will allocate
7689      at least two ODR streams - one for decoding, and one for encoding.
7690     </para>
7691     <para>
7692      When you're done with the stream, you can use
7693     </para>
7694     <synopsis>
7695      void odr_destroy(ODR o);
7696     </synopsis>
7697     <para>
7698      to release the resources allocated for the stream.
7699     </para>
7700    </sect2>
7701    <sect2 id="odr.memory.management">
7702     <title id="memory">Memory Management</title>
7703     <para>
7704      Two forms of memory management take place in the &odr; system. The first
7705      one, which has to do with allocating little bits of memory (sometimes
7706      quite large bits of memory, actually) when a protocol package is
7707      decoded, and turned into a complex of interlinked structures. This
7708      section deals with this system, and how you can use it for your own
7709      purposes. The next section deals with the memory management which is
7710      required when encoding data - to make sure that a large enough buffer is
7711      available to hold the fully encoded PDU.
7712     </para>
7713     <para>
7714      The &odr; module has its own memory management system, which is
7715      used whenever memory is required. Specifically, it is used to allocate
7716      space for data when decoding incoming PDUs. You can use the memory
7717      system for your own purposes, by using the function
7718     </para>
7719     <synopsis>
7720      void *odr_malloc(ODR o, size_t size);
7721     </synopsis>
7722     <para>
7723      You can't use the normal <function>free(2)</function> routine to free
7724      memory allocated by this function, and &odr; doesn't provide a parallel
7725      function. Instead, you can call
7726     </para>
7727     <synopsis>
7728      void odr_reset(ODR o);
7729     </synopsis>
7730     <para>
7731      when you are done with the
7732      memory: Everything allocated since the last call to
7733      <function>odr_reset()</function> is released.
7734      The <function>odr_reset()</function> call is also required to clear
7735      up an error condition on a stream.
7736     </para>
7737     <para>
7738      The function
7739     </para>
7740     <synopsis>
7741      size_t odr_total(ODR o);
7742     </synopsis>
7743     <para>
7744      returns the number of bytes allocated on the stream since the last call to
7745      <function>odr_reset()</function>.
7746     </para>
7747     <para>
7748      The memory subsystem of &odr; is fairly efficient at allocating and
7749      releasing little bits of memory. Rather than managing the individual,
7750      small bits of space, the system maintains a free-list of larger chunks
7751      of memory, which are handed out in small bits. This scheme is
7752      generally known as a <emphasis>nibble memory</emphasis> system.
7753      It is very useful for maintaining short-lived constructions such
7754      as protocol PDUs.
7755     </para>
7756     <para>
7757      If you want to retain a bit of memory beyond the next call to
7758      <function>odr_reset()</function>, you can use the function
7759     </para>
7760     <synopsis>
7761      ODR_MEM odr_extract_mem(ODR o);
7762     </synopsis>
7763     <para>
7764      This function will give you control of the memory recently allocated
7765      on the ODR stream. The memory will live (past calls to
7766      <function>odr_reset()</function>), until you call the function
7767     </para>
7768     <synopsis>
7769      void odr_release_mem(ODR_MEM p);
7770     </synopsis>
7771     <para>
7772      The opaque <literal>ODR_MEM</literal> handle has no other purpose than
7773      referencing the memory block for you until you want to release it.
7774     </para>
7775     <para>
7776      You can use <function>odr_extract_mem()</function> repeatedly between
7777      allocating data, to retain individual control of separate chunks of data.
7778     </para>
7779    </sect2>
7780    <sect2 id="odr.encoding.and.decoding">
7781     <title>Encoding and Decoding Data</title>
7782     <para>
7783      When encoding data, the ODR stream will write the encoded octet string
7784      in an internal buffer. To retrieve the data, use the function
7785     </para>
7786     <synopsis>
7787      char *odr_getbuf(ODR o, int *len, int *size);
7788     </synopsis>
7789     <para>
7790      The integer pointed to by len is set to the length of the encoded
7791      data, and a pointer to that data is returned. <literal>*size</literal>
7792      is set to the size of the buffer (unless <literal>size</literal> is null,
7793      signaling that you are not interested in the size). The next call to
7794      a primitive function using the same &odr; stream will overwrite the
7795      data, unless a different buffer has been supplied using the call
7796     </para>
7797     <synopsis>
7798      void odr_setbuf(ODR o, char *buf, int len, int can_grow);
7799     </synopsis>
7800     <para>
7801      which sets the encoding (or decoding) buffer used by
7802      <literal>o</literal> to <literal>buf</literal>, using the length
7803      <literal>len</literal>.
7804      Before a call to an encoding function, you can use
7805      <function>odr_setbuf()</function> to provide the stream with an encoding
7806      buffer of sufficient size (length). The <literal>can_grow</literal>
7807      parameter tells the encoding &odr; stream whether it is allowed to use
7808      <function>realloc(2)</function> to increase the size of the buffer when
7809      necessary. The default condition of a new encoding stream is equivalent
7810      to the results of calling
7811     </para>
7812     <synopsis>
7813      odr_setbuf(stream, 0, 0, 1);
7814     </synopsis>
7815     <para>
7816      In this case, the stream will allocate and reallocate memory as
7817      necessary. The stream reallocates memory by repeatedly doubling the
7818      size of the buffer - the result is that the buffer will typically
7819      reach its maximum, working size with only a small number of reallocation
7820      operations. The memory is freed by the stream when the latter is destroyed,
7821      unless it was assigned by the user with the <literal>can_grow</literal>
7822      parameter set to zero (in this case, you are expected to retain
7823      control of the memory yourself).
7824     </para>
7825     <para>
7826      To assume full control of an encoded buffer, you must first call
7827      <function>odr_getbuf()</function> to fetch the buffer and its length.
7828      Next, you should call <function>odr_setbuf()</function> to provide a
7829      different buffer (or a null pointer) to the stream. In the simplest
7830      case, you will reuse the same buffer over and over again, and you
7831      will just need to call <function>odr_getbuf()</function> after each
7832      encoding operation to get the length and address of the buffer.
7833      Note that the stream may reallocate the buffer during an encoding
7834      operation, so it is necessary to retrieve the correct address after
7835      each encoding operation.
7836     </para>
7837     <para>
7838      It is important to realize that the ODR stream will not release this
7839      memory when you call <function>odr_reset()</function>: It will
7840      merely update its internal pointers to prepare for the encoding of a
7841      new data value.
7842      When the stream is released by the <function>odr_destroy()</function>
7843      function, the memory given to it by <function>odr_setbuf</function> will
7844      be released <emphasis>only</emphasis> if the <literal>can_grow</literal>
7845      parameter to <function>odr_setbuf()</function> was nonzero. The
7846      <literal>can_grow</literal> parameter, in other words, is a way of
7847      signaling who is to own the buffer, you or the ODR stream. If you never call
7848      <function>odr_setbuf()</function> on your encoding stream, which is
7849      typically the case, the buffer allocated by the stream will belong to
7850      the stream by default.
7851     </para>
7852     <para>
7853      When you wish to decode data, you should first call
7854      <function>odr_setbuf()</function>, to tell the decoding stream
7855      where to find the encoded data, and how long the buffer is
7856      (the <literal>can_grow</literal> parameter is ignored by a decoding
7857      stream). After this, you can call the function corresponding to the
7858      data you wish to decode (eg, <function>odr_integer()</function> odr
7859      <function>z_APDU()</function>).
7860     </para>
7861     <example id="example.odr.encoding.and.decoding.functions">
7862      <title>Encoding and decoding functions</title>
7863      <synopsis>
7864       int odr_integer(ODR o, Odr_int **p, int optional, const char *name);
7865
7866       int z_APDU(ODR o, Z_APDU **p, int optional, const char *name);
7867      </synopsis>
7868     </example>
7869     <para>
7870      If the data is absent (or doesn't match the tag corresponding to
7871      the type), the return value will be either 0 or 1 depending on the
7872      <literal>optional</literal> flag. If <literal>optional</literal>
7873      is 0 and the data is absent, an error flag will be raised in the
7874      stream, and you'll need to call <function>odr_reset()</function> before
7875      you can use the stream again. If <literal>optional</literal> is
7876      nonzero, the pointer <emphasis>pointed</emphasis> to/ by
7877      <literal>p</literal> will be set to the null value, and the function
7878      will return 1.
7879      The <literal>name</literal> argument is used to pretty-print the
7880      tag in question. It may be set to <literal>NULL</literal> if
7881      pretty-printing is not desired.
7882     </para>
7883     <para>
7884      If the data value is found where it's expected, the pointer
7885      <emphasis>pointed to</emphasis> by the <literal>p</literal> argument
7886      will be set to point to the decoded type.
7887      The space for the type will be allocated and owned by the &odr;
7888      stream, and it will live until you call
7889      <function>odr_reset()</function> on the stream. You cannot use
7890      <function>free(2)</function> to release the memory.
7891      You can decode several data elements (by repeated calls to
7892      <function>odr_setbuf()</function> and your decoding function), and
7893      new memory will be allocated each time. When you do call
7894      <function>odr_reset()</function>, everything decoded since the
7895      last call to <function>odr_reset()</function> will be released.
7896     </para>
7897     <example id="example.odr.encoding.of.integer">
7898      <title>Encoding and decoding of an integer</title>
7899      <para>
7900       The use of the double indirection can be a little confusing at first
7901       (its purpose will become clear later on, hopefully),
7902       so an example is in order. We'll encode an integer value, and
7903       immediately decode it again using a different stream. A useless, but
7904       informative operation.
7905      </para>
7906      <programlisting><![CDATA[
7907 void do_nothing_useful(Odr_int value)
7908 {
7909     ODR encode, decode;
7910     Odr_int *valp, *resvalp;
7911     char *bufferp;
7912     int len;
7913
7914     /* allocate streams */
7915     if (!(encode = odr_createmem(ODR_ENCODE)))
7916         return;
7917     if (!(decode = odr_createmem(ODR_DECODE)))
7918         return;
7919
7920     valp = &value;
7921     if (odr_integer(encode, &valp, 0, 0) == 0)
7922     {
7923         printf("encoding went bad\n");
7924         return;
7925     }
7926     bufferp = odr_getbuf(encode, &len, 0);
7927     printf("length of encoded data is %d\n", len);
7928
7929     /* now let's decode the thing again */
7930     odr_setbuf(decode, bufferp, len, 0);
7931     if (odr_integer(decode, &resvalp, 0, 0) == 0)
7932     {
7933         printf("decoding went bad\n");
7934         return;
7935     }
7936     /* ODR_INT_PRINTF format for printf (such as %d) */
7937     printf("the value is " ODR_INT_PRINTF "\n", *resvalp);
7938
7939     /* clean up */
7940     odr_destroy(encode);
7941     odr_destroy(decode);
7942 }
7943 ]]>
7944      </programlisting>
7945      <para>
7946       This looks like a lot of work, offhand. In practice, the &odr; streams
7947       will typically be allocated once, in the beginning of your program
7948       (or at the beginning of a new network session), and the encoding
7949       and decoding will only take place in a few, isolated places in your
7950       program, so the overhead is quite manageable.
7951      </para>
7952     </example>
7953    </sect2>
7954    <sect2 id="odr.printing">
7955     <title>Printing</title>
7956     <para>
7957      When an ODR stream is created of type <literal>ODR_PRINT</literal>
7958      the ODR module will print the contents of a PDU in a readable format.
7959      By default output is written to the <literal>stderr</literal> stream.
7960      This behavior can be changed, however, by calling the function
7961      <synopsis>
7962       odr_setprint(ODR o, FILE *file);
7963      </synopsis>
7964      before encoders or decoders are being invoked.
7965      It is also possible to direct the output to a buffer (of indeed
7966      another file), by using the more generic mechanism:
7967      <synopsis>
7968       void odr_set_stream(ODR o, void *handle,
7969                          void (*stream_write)(ODR o, void *handle, int type,
7970                                               const char *buf, int len),
7971                          void (*stream_close)(void *handle));
7972      </synopsis>
7973      Here the user provides an opaque handle and two handlers,
7974      <replaceable>stream_write</replaceable> for writing,
7975      and <replaceable>stream_close</replaceable> which is supposed
7976      to close/free resources associated with handle.
7977      The <replaceable>stream_close</replaceable> handler is optional and
7978      if NULL for the function is provided, it will not be invoked.
7979      The <replaceable>stream_write</replaceable> takes the ODR handle
7980      as parameter, the user defined handle, a type
7981      <literal>ODR_OCTETSTRING</literal>, <literal>ODR_VISIBLESTRING</literal>
7982      which indicates the type of contents is being written.
7983     </para>
7984     <para>
7985      Another utility useful for diagnostics (error handling) or as
7986      part of the printing facilities is:
7987      <synopsis>
7988       const char **odr_get_element_path(ODR o);
7989      </synopsis>
7990      which returns a list of current elements that ODR deals with at the
7991      moment. For the returned array, say <literal>ar</literal>,
7992      <literal>ar[0]</literal> is the top level element,
7993      <literal>ar[n]</literal> is the last. The last element has the
7994      property that <literal>ar[n+1] == NULL</literal>.
7995     </para>
7996     <example id="example.odr.element.path.record">
7997      <title>Element Path for record</title>
7998      <para>
7999       For a database record part of a PresentResponse the
8000       array returned by <function>odr_get_element</function>
8001       is <literal>presentResponse</literal>, <literal>databaseOrSurDiagnostics</literal>, <literal>?</literal>, <literal>record</literal>, <literal>?</literal>, <literal>databaseRecord</literal> . The question mark appears due to
8002       unnamed constructions.
8003      </para>
8004     </example>
8005    </sect2>
8006    <sect2 id="odr.diagnostics">
8007     <title>Diagnostics</title>
8008     <para>
8009      The encoding/decoding functions all return 0 when an error occurs.
8010      Until you call <function>odr_reset()</function>, you cannot use the
8011      stream again, and any function called will immediately return 0.
8012     </para>
8013     <para>
8014      To provide information to the programmer or administrator, the function
8015     </para>
8016     <synopsis>
8017      void odr_perror(ODR o, char *message);
8018     </synopsis>
8019     <para>
8020      is provided, which prints the <literal>message</literal> argument to
8021      <literal>stderr</literal> along with an error message from the stream.
8022     </para>
8023     <para>
8024      You can also use the function
8025     </para>
8026     <synopsis>
8027      int odr_geterror(ODR o);
8028     </synopsis>
8029     <para>
8030      to get the current error number from the screen. The number will be
8031      one of these constants:
8032     </para>
8033     <table frame="top" id="odr.error.codes">
8034      <title>ODR Error codes</title>
8035      <tgroup cols="2">
8036       <thead>
8037        <row>
8038         <entry>code</entry>
8039         <entry>Description</entry>
8040        </row>
8041       </thead>
8042       <tbody>
8043        <row>
8044         <entry>OMEMORY</entry><entry>Memory allocation failed.</entry>
8045        </row>
8046        <row>
8047         <entry>OSYSERR</entry><entry>A system- or library call has failed.
8048          The standard diagnostic variable <literal>errno</literal> should be
8049          examined to determine the actual error.</entry>
8050        </row>
8051        <row>
8052         <entry>OSPACE</entry><entry>No more space for encoding.
8053          This will only occur when the user has explicitly provided a
8054          buffer for an encoding stream without allowing the system to
8055          allocate more space.</entry>
8056        </row>
8057        <row>
8058         <entry>OREQUIRED</entry><entry>This is a common protocol error; A
8059          required data element was missing during encoding or decoding.</entry>
8060        </row>
8061        <row>
8062         <entry>OUNEXPECTED</entry><entry>An unexpected data element was
8063         found during decoding.</entry>
8064        </row>
8065        <row>
8066         <entry>OOTHER</entry><entry>Other error. This is typically an
8067         indication of misuse of the &odr; system by the programmer, and also
8068         that the diagnostic system isn't as good as it should be, yet.</entry>
8069        </row>
8070       </tbody>
8071      </tgroup>
8072     </table>
8073     <para>
8074      The character string array
8075     </para>
8076     <synopsis>
8077      char *odr_errlist[]
8078     </synopsis>
8079     <para>
8080      can be indexed by the error code to obtain a human-readable
8081      representation of the problem.
8082     </para>
8083    </sect2>
8084    <sect2 id="odr.summary.and.synopsis">
8085     <title>Summary and Synopsis</title>
8086     <synopsis>
8087      #include &lt;yaz/odr.h>
8088
8089      ODR odr_createmem(int direction);
8090
8091      void odr_destroy(ODR o);
8092
8093      void odr_reset(ODR o);
8094
8095      char *odr_getbuf(ODR o, int *len, int *size);
8096
8097      void odr_setbuf(ODR o, char *buf, int len, int can_grow);
8098
8099      void *odr_malloc(ODR o, int size);
8100
8101      NMEM odr_extract_mem(ODR o);
8102
8103      int odr_geterror(ODR o);
8104
8105      void odr_perror(ODR o, const char *message);
8106
8107      extern char *odr_errlist[];
8108     </synopsis>
8109    </sect2>
8110   </sect1>
8111   <sect1 id="odr.programming">
8112    <title>Programming with ODR</title>
8113    <para>
8114     The API of &odr; is designed to reflect the structure of ASN.1, rather
8115     than BER itself. Future releases may be able to represent data in
8116     other external forms.
8117    </para>
8118    <tip>
8119     <para>
8120      There is an ASN.1 tutorial available at
8121      <ulink url="&url.asn.1.tutorial;">this site</ulink>.
8122      This site also has standards for ASN.1 (X.680) and BER (X.690)
8123      <ulink url="&url.asn.1.standards;">online</ulink>.
8124     </para>
8125    </tip>
8126    <para>
8127     The ODR interface is based loosely on that of the Sun Microsystems
8128     XDR routines.
8129     Specifically, each function which corresponds to an ASN.1 primitive
8130     type has a dual function. Depending on the settings of the ODR
8131     stream which is supplied as a parameter, the function may be used
8132     either to encode or decode data. The functions that can be built
8133     using these primitive functions, to represent more complex data types,
8134     share this quality. The result is that you only have to enter the
8135     definition for a type once - and you have the functionality of encoding,
8136     decoding (and pretty-printing) all in one unit.
8137     The resulting C source code is quite compact, and is a pretty
8138     straightforward representation of the source ASN.1 specification.
8139    </para>
8140    <para>
8141     In many cases, the model of the XDR functions works quite well in this
8142     role.
8143     In others, it is less elegant. Most of the hassle comes from the optional
8144     SEQUENCE members which don't exist in XDR.
8145    </para>
8146    <sect2 id="odr.primitive.asn1.types">
8147     <title>The Primitive ASN.1 Types</title>
8148     <para>
8149      ASN.1 defines a number of primitive types (many of which correspond
8150      roughly to primitive types in structured programming languages, such as C).
8151     </para>
8152     <sect3 id="odr.integer">
8153      <title>INTEGER</title>
8154      <para>
8155       The &odr; function for encoding or decoding (or printing) the ASN.1
8156       INTEGER type looks like this:
8157      </para>
8158      <synopsis>
8159       int odr_integer(ODR o, Odr_int **p, int optional, const char *name);
8160      </synopsis>
8161      <para>
8162       The <literal>Odr_int</literal> is just a simple integer.
8163      </para>
8164      <para>
8165       This form is typical of the primitive &odr; functions. They are named
8166       after the type of data that they encode or decode. They take an &odr;
8167       stream, an indirect reference to the type in question, and an
8168       <literal>optional</literal> flag (corresponding to the OPTIONAL keyword
8169       of ASN.1) as parameters. They all return an integer value of either one
8170       or zero.
8171       When you use the primitive functions to construct encoders for complex
8172       types of your own, you should follow this model as well. This
8173       ensures that your new types can be reused as elements in yet more
8174       complex types.
8175      </para>
8176      <para>
8177       The <literal>o</literal> parameter should obviously refer to a properly
8178       initialized &odr; stream of the right type (encoding/decoding/printing)
8179       for the operation that you wish to perform.
8180      </para>
8181      <para>
8182       When encoding or printing, the function first looks at
8183       <literal>* p</literal>. If <literal>* p</literal> (the pointer pointed
8184       to by <literal>p</literal>) is a null pointer, this is taken to mean that
8185       the data element is absent. If the <literal>optional</literal> parameter
8186       is nonzero, the function will return one (signifying success) without
8187       any further processing. If the <literal>optional</literal> is zero, an
8188       internal error flag is set in the &odr; stream, and the function will
8189       return 0. No further operations can be carried out on the stream without
8190       a call to the function <function>odr_reset()</function>.
8191      </para>
8192      <para>
8193       If <literal>*p</literal> is not a null pointer, it is expected to
8194       point to an instance of the data type. The data will be subjected to
8195       the encoding rules, and the result will be placed in the buffer held
8196       by the &odr; stream.
8197      </para>
8198      <para>
8199       The other ASN.1 primitives have similar functions that operate in
8200       similar manners:
8201      </para>
8202     </sect3>
8203     <sect3 id="odr.boolean">
8204      <title>BOOLEAN</title>
8205      <synopsis>
8206 int odr_bool(ODR o, Odr_bool **p, int optional, const char *name);
8207      </synopsis>
8208     </sect3>
8209     <sect3 id="odr.real">
8210      <title>REAL</title>
8211      <para>
8212       Not defined.
8213      </para>
8214     </sect3>
8215     <sect3 id="odr.null">
8216      <title>NULL</title>
8217      <synopsis>
8218 int odr_null(ODR o, Odr_null **p, int optional, const char *name);
8219      </synopsis>
8220      <para>
8221       In this case, the value of **p is not important. If <literal>*p</literal>
8222       is different from the null pointer, the null value is present, otherwise
8223       it's absent.
8224      </para>
8225     </sect3>
8226     <sect3 id="odr.octet.string">
8227      <title>OCTET STRING</title>
8228      <synopsis>
8229 typedef struct odr_oct
8230 {
8231     unsigned char *buf;
8232     int len;
8233 } Odr_oct;
8234
8235 int odr_octetstring(ODR o, Odr_oct **p, int optional,
8236                     const char *name);
8237      </synopsis>
8238      <para>
8239       The <literal>buf</literal> field should point to the character array
8240       that holds the octetstring. The <literal>len</literal> field holds the
8241       actual length.
8242       The character array need not be null terminated.
8243      </para>
8244      <para>
8245       To make things a little easier, an alternative is given for string
8246       types that are not expected to contain embedded NULL characters (eg.
8247       VisibleString):
8248      </para>
8249      <synopsis>
8250       int odr_cstring(ODR o, char **p, int optional, const char *name);
8251      </synopsis>
8252      <para>
8253       Which encoded or decodes between OCTETSTRING representations and
8254       null-terminates C strings.
8255      </para>
8256      <para>
8257       Functions are provided for the derived string types, eg:
8258      </para>
8259      <synopsis>
8260 int odr_visiblestring(ODR o, char **p, int optional,
8261                       const char *name);
8262      </synopsis>
8263     </sect3>
8264     <sect3 id="odr.bit.string">
8265      <title>BIT STRING</title>
8266      <synopsis>
8267 int odr_bitstring(ODR o, Odr_bitmask **p, int optional,
8268                   const char *name);
8269      </synopsis>
8270      <para>
8271       The opaque type <literal>Odr_bitmask</literal> is only suitable for
8272       holding relatively brief bit strings, eg. for options fields, etc.
8273       The constant <literal>ODR_BITMASK_SIZE</literal> multiplied by 8
8274       gives the maximum possible number of bits.
8275      </para>
8276      <para>
8277       A set of macros are provided for manipulating the
8278       <literal>Odr_bitmask</literal> type:
8279      </para>
8280      <synopsis>
8281 void ODR_MASK_ZERO(Odr_bitmask *b);
8282
8283 void ODR_MASK_SET(Odr_bitmask *b, int bitno);
8284
8285 void ODR_MASK_CLEAR(Odr_bitmask *b, int bitno);
8286
8287 int ODR_MASK_GET(Odr_bitmask *b, int bitno);
8288      </synopsis>
8289      <para>
8290       The functions are modeled after the manipulation functions that
8291       accompany the <literal>fd_set</literal> type used by the
8292       <function>select(2)</function> call.
8293       <literal>ODR_MASK_ZERO</literal> should always be called first on a
8294       new bitmask, to initialize the bits to zero.
8295      </para>
8296     </sect3>
8297     <sect3 id="odr.object.identifier">
8298      <title>OBJECT IDENTIFIER</title>
8299      <synopsis>
8300 int odr_oid(ODR o, Odr_oid **p, int optional, const char *name);
8301      </synopsis>
8302      <para>
8303       The C OID representation is simply an array of integers, terminated by
8304       the value -1 (the <literal>Odr_oid</literal> type is synonymous with
8305       the <literal>short</literal> type).
8306       We suggest that you use the OID database module (see
8307       <xref linkend="tools.oid.database"/>) to handle object identifiers
8308       in your application.
8309      </para>
8310     </sect3>
8311    </sect2>
8312    <sect2 id="odr.tagging.primitive.types">
8313     <title>Tagging Primitive Types</title>
8314     <para>
8315      The simplest way of tagging a type is to use the
8316      <function>odr_implicit_tag()</function> or
8317      <function>odr_explicit_tag()</function> macros:
8318     </para>
8319     <synopsis>
8320 int odr_implicit_tag(ODR o, Odr_fun fun, int class, int tag,
8321                      int optional, const char *name);
8322
8323 int odr_explicit_tag(ODR o, Odr_fun fun, int class, int tag,
8324                      int optional, const char *name);
8325     </synopsis>
8326     <para>
8327      To create a type derived from the integer type by implicit tagging, you
8328      might write:
8329     </para>
8330     <screen>
8331      MyInt ::= [210] IMPLICIT INTEGER
8332     </screen>
8333     <para>
8334      In the &odr; system, this would be written like:
8335     </para>
8336     <screen>
8337 int myInt(ODR o, Odr_int **p, int optional, const char *name)
8338 {
8339     return odr_implicit_tag(o, odr_integer, p,
8340                             ODR_CONTEXT, 210, optional, name);
8341 }
8342     </screen>
8343     <para>
8344      The function <function>myInt()</function> can then be used like any of
8345      the primitive functions provided by &odr;. Note that the behavior of
8346      <function>odr_explicit_tag()</function>
8347      and <function>odr_implicit_tag()</function> macros
8348      act exactly the same as the functions they are applied to - they
8349      respond to error conditions, etc, in the same manner - they
8350      simply have three extra parameters. The class parameter may
8351      take one of the values: <literal>ODR_CONTEXT</literal>,
8352      <literal>ODR_PRIVATE</literal>, <literal>ODR_UNIVERSAL</literal>, or
8353      <literal>/ODR_APPLICATION</literal>.
8354     </para>
8355    </sect2>
8356    <sect2 id="odr.constructed.types">
8357     <title>Constructed Types</title>
8358     <para>
8359      Constructed types are created by combining primitive types. The
8360       &odr; system only implements the SEQUENCE and SEQUENCE OF constructions
8361      (although adding the rest of the container types should be simple
8362      enough, if the need arises).
8363     </para>
8364     <para>
8365      For implementing SEQUENCEs, the functions
8366     </para>
8367     <synopsis>
8368 int odr_sequence_begin(ODR o, void *p, int size, const char *name);
8369 int odr_sequence_end(ODR o);
8370     </synopsis>
8371     <para>
8372      are provided.
8373     </para>
8374     <para>
8375      The <function>odr_sequence_begin()</function> function should be
8376      called in the beginning of a function that implements a SEQUENCE type.
8377      Its parameters are the &odr; stream, a pointer (to a pointer to the type
8378      you're implementing), and the <literal>size</literal> of the type
8379      (typically a C structure). On encoding, it returns 1 if
8380      <literal>* p</literal> is a null pointer. The <literal>size</literal>
8381      parameter is ignored. On decoding, it returns 1 if the type is found in
8382      the data stream. <literal>size</literal> bytes of memory are allocated,
8383      and <literal>*p</literal> is set to point to this space.
8384      <function>odr_sequence_end()</function> is called at the end of the
8385      complex function. Assume that a type is defined like this:
8386     </para>
8387     <screen>
8388 MySequence ::= SEQUENCE {
8389      intval INTEGER,
8390      boolval BOOLEAN OPTIONAL
8391 }
8392     </screen>
8393     <para>
8394      The corresponding &odr; encoder/decoder function and the associated data
8395      structures could be written like this:
8396     </para>
8397     <screen>
8398 typedef struct MySequence
8399 {
8400     Odr_int *intval;
8401     Odr_bool *boolval;
8402 } MySequence;
8403
8404 int mySequence(ODR o, MySequence **p, int optional, const char *name)
8405 {
8406     if (odr_sequence_begin(o, p, sizeof(**p), name) == 0)
8407         return optional &amp;&amp; odr_ok(o);
8408     return
8409         odr_integer(o, &amp;(*p)->intval, 0, "intval") &amp;&amp;
8410         odr_bool(o, &amp;(*p)->boolval, 1, "boolval") &amp;&amp;
8411         odr_sequence_end(o);
8412 }
8413     </screen>
8414     <para>
8415      Note the 1 in the call to <function>odr_bool()</function>, to mark
8416      that the sequence member is optional.
8417      If either of the member types had been tagged, the macros
8418      <function>odr_implicit_tag()</function> or
8419      <function>odr_explicit_tag()</function>
8420      could have been used.
8421      The new function can be used exactly like the standard functions provided
8422      with &odr;. It will encode, decode or pretty-print a data value of the
8423      <literal>MySequence</literal> type. We like to name types with an
8424      initial capital, as done in ASN.1 definitions, and to name the
8425      corresponding function with the first character of the name in lower case.
8426      You could, of course, name your structures, types, and functions any way
8427      you please - as long as you're consistent, and your code is easily readable.
8428      <literal>odr_ok</literal> is just that - a predicate that returns the
8429      state of the stream. It is used to ensure that the behavior of the new
8430      type is compatible with the interface of the primitive types.
8431     </para>
8432    </sect2>
8433    <sect2 id="odr.tagging.constructed.types">
8434     <title>Tagging Constructed Types</title>
8435     <note>
8436      <para>
8437       See <xref linkend="odr.tagging.primitive.types"/> for information
8438       on how to tag the primitive types, as well as types that are
8439       already defined.
8440      </para>
8441     </note>
8442     <sect3 id="odr.implicit.tagging">
8443      <title>Implicit Tagging</title>
8444      <para>
8445       Assume the type above had been defined as
8446      </para>
8447      <screen>
8448 MySequence ::= [10] IMPLICIT SEQUENCE {
8449       intval INTEGER,
8450       boolval BOOLEAN OPTIONAL
8451 }
8452      </screen>
8453      <para>
8454       You would implement this in &odr; by calling the function
8455      </para>
8456      <synopsis>
8457 int odr_implicit_settag(ODR o, int class, int tag);
8458      </synopsis>
8459      <para>
8460       which overrides the tag of the type immediately following it. The
8461       macro <function>odr_implicit_tag()</function> works by calling
8462       <function>odr_implicit_settag()</function> immediately
8463       before calling the function pointer argument.
8464       Your type function could look like this:
8465      </para>
8466      <screen>
8467 int mySequence(ODR o, MySequence **p, int optional, const char *name)
8468 {
8469     if (odr_implicit_settag(o, ODR_CONTEXT, 10) == 0 ||
8470         odr_sequence_begin(o, p, sizeof(**p), name) == 0)
8471         return optional &amp;&amp; odr_ok(o);
8472     return
8473         odr_integer(o, &amp;(*p)->intval, 0, "intval") &amp;&amp;
8474         odr_bool(o, &amp;(*p)->boolval, 1, "boolval") &amp;&amp;
8475         odr_sequence_end(o);
8476 }
8477      </screen>
8478      <para>
8479       The definition of the structure <literal>MySequence</literal> would be
8480       the same.
8481      </para>
8482     </sect3>
8483     <sect3 id="odr.explicit.tagging">
8484      <title>Explicit Tagging</title>
8485      <para>
8486       Explicit tagging of constructed types is a little more complicated,
8487       since you are in effect adding a level of construction to the data.
8488      </para>
8489      <para>
8490       Assume the definition:
8491      </para>
8492      <screen>
8493 MySequence ::= [10] IMPLICIT SEQUENCE {
8494    intval INTEGER,
8495    boolval BOOLEAN OPTIONAL
8496 }
8497      </screen>
8498      <para>
8499       Since the new type has an extra level of construction, two new functions
8500       are needed to encapsulate the base type:
8501      </para>
8502      <synopsis>
8503 int odr_constructed_begin(ODR o, void *p, int class, int tag,
8504                           const char *name);
8505
8506 int odr_constructed_end(ODR o);
8507      </synopsis>
8508      <para>
8509       Assume that the IMPLICIT in the type definition above were replaced
8510       with EXPLICIT (or that the IMPLICIT keyword were simply deleted, which
8511       would be equivalent). The structure definition would look the same,
8512       but the function would look like this:
8513      </para>
8514      <screen>
8515 int mySequence(ODR o, MySequence **p, int optional, const char *name)
8516 {
8517     if (odr_constructed_begin(o, p, ODR_CONTEXT, 10, name) == 0)
8518         return optional &amp;&amp; odr_ok(o);
8519     if (o->direction == ODR_DECODE)
8520         *p = odr_malloc(o, sizeof(**p));
8521     if (odr_sequence_begin(o, p, sizeof(**p), 0) == 0)
8522     {
8523         *p = 0; /* this is almost certainly a protocol error */
8524         return 0;
8525     }
8526     return
8527         odr_integer(o, &amp;(*p)->intval, 0, "intval") &amp;&amp;
8528         odr_bool(o, &amp;(*p)->boolval, 1, "boolval") &amp;&amp;
8529         odr_sequence_end(o) &amp;&amp;
8530         odr_constructed_end(o);
8531 }
8532      </screen>
8533      <para>
8534       Notice that the interface here gets kind of nasty. The reason is
8535       simple: Explicitly tagged, constructed types are fairly rare in
8536       the protocols that we care about, so the
8537       esthetic annoyance (not to mention the dangers of a cluttered
8538       interface) is less than the time that would be required to develop a
8539       better interface. Nevertheless, it is far from satisfying, and it's a
8540       point that will be worked on in the future. One option for you would
8541       be to simply apply the <function>odr_explicit_tag()</function> macro to
8542       the first function, and not
8543       have to worry about <function>odr_constructed_*</function> yourself.
8544       Incidentally, as you might have guessed, the
8545       <function>odr_sequence_</function> functions are themselves
8546       implemented using the <function>/odr_constructed_</function> functions.
8547      </para>
8548     </sect3>
8549    </sect2>
8550    <sect2 id="odr.sequence.of">
8551     <title>SEQUENCE OF</title>
8552     <para>
8553      To handle sequences (arrays) of a specific type, the function
8554     </para>
8555     <synopsis>
8556 int odr_sequence_of(ODR o, int (*fun)(ODR o, void *p, int optional),
8557                     void *p, int *num, const char *name);
8558     </synopsis>
8559     <para>
8560      The <literal>fun</literal> parameter is a pointer to the decoder/encoder
8561      function of the type. <literal>p</literal> is a pointer to an array of
8562      pointers to your type. <literal>num</literal> is the number of elements
8563      in the array.
8564     </para>
8565     <para>
8566      Assume a type
8567     </para>
8568     <screen>
8569 MyArray ::= SEQUENCE OF INTEGER
8570     </screen>
8571     <para>
8572      The C representation might be
8573     </para>
8574     <screen>
8575 typedef struct MyArray
8576 {
8577     int num_elements;
8578     Odr_int **elements;
8579 } MyArray;
8580     </screen>
8581     <para>
8582      And the function might look like
8583     </para>
8584     <screen>
8585 int myArray(ODR o, MyArray **p, int optional, const char *name)
8586 {
8587     if (o->direction == ODR_DECODE)
8588         *p = odr_malloc(o, sizeof(**p));
8589     if (odr_sequence_of(o, odr_integer, &amp;(*p)->elements,
8590         &amp;(*p)->num_elements, name))
8591         return 1;
8592     *p = 0;
8593         return optional &amp;&amp; odr_ok(o);
8594 }
8595     </screen>
8596    </sect2>
8597    <sect2 id="odr.choice.types">
8598     <title>CHOICE Types</title>
8599     <para>
8600      The choice type is used fairly often in some ASN.1 definitions, so
8601      some work has gone into streamlining its interface.
8602     </para>
8603     <para>
8604      CHOICE types are handled by the function:
8605     </para>
8606     <synopsis>
8607 int odr_choice(ODR o, Odr_arm arm[], void *p, void *whichp,
8608                const char *name);
8609     </synopsis>
8610     <para>
8611      The <literal>arm</literal> array is used to describe each of the possible
8612      types that the CHOICE type may assume. Internally in your application,
8613      the CHOICE type is represented as a discriminated union. That is, a
8614      C union accompanied by an integer (or enum) identifying the active
8615      'arm' of the union.
8616      <literal>whichp</literal> is a pointer to the union discriminator.
8617      When encoding, it is examined to determine the current type.
8618      When decoding, it is set to reference the type that was found in
8619      the input stream.
8620     </para>
8621     <para>
8622      The Odr_arm type is defined thus:
8623     </para>
8624     <screen>
8625 typedef struct odr_arm
8626 {
8627     int tagmode;
8628     int class;
8629     int tag;
8630     int which;
8631     Odr_fun fun;
8632     char *name;
8633 } Odr_arm;
8634     </screen>
8635     <para>
8636      The interpretation of the fields are:
8637     </para>
8638     <variablelist>
8639      <varlistentry>
8640       <term>tagmode</term>
8641       <listitem><para>Either <literal>ODR_IMPLICIT</literal>,
8642       <literal>ODR_EXPLICIT</literal>, or <literal>ODR_NONE</literal> (-1)
8643       to mark   no tagging.</para></listitem>
8644      </varlistentry>
8645      <varlistentry>
8646       <term>which</term>
8647       <listitem><para>The value of the discriminator that corresponds to
8648       this CHOICE element. Typically, it will be a #defined constant, or
8649       an enum member.</para></listitem>
8650      </varlistentry>
8651      <varlistentry>
8652       <term>fun</term>
8653       <listitem><para>A pointer to a function that implements the type of
8654       the CHOICE member. It may be either a standard &odr; type or a type
8655       defined by yourself.</para></listitem>
8656      </varlistentry>
8657      <varlistentry>
8658       <term>name</term>
8659       <listitem><para>Name of tag.</para></listitem>
8660      </varlistentry>
8661     </variablelist>
8662     <para>
8663      A handy way to prepare the array for use by the
8664      <function>odr_choice()</function> function is to
8665      define it as a static, initialized array in the beginning of your
8666      decoding/encoding function. Assume the type definition:
8667     </para>
8668     <screen>
8669 MyChoice ::= CHOICE {
8670     untagged INTEGER,
8671     tagged   [99] IMPLICIT INTEGER,
8672     other    BOOLEAN
8673 }
8674     </screen>
8675     <para>
8676      Your C type might look like
8677     </para>
8678     <screen>
8679 typedef struct MyChoice
8680 {
8681     enum
8682     {
8683         MyChoice_untagged,
8684         MyChoice_tagged,
8685         MyChoice_other
8686     } which;
8687     union
8688     {
8689         Odr_int *untagged;
8690         Odr_int *tagged;
8691         Odr_bool *other;
8692     } u;
8693 };
8694     </screen>
8695     <para>
8696      And your function could look like this:
8697     </para>
8698     <screen>
8699 int myChoice(ODR o, MyChoice **p, int optional, const char *name)
8700 {
8701     static Odr_arm arm[] =
8702     {
8703       {-1, -1, -1, MyChoice_untagged, odr_integer, "untagged"},
8704       {ODR_IMPLICIT, ODR_CONTEXT, 99, MyChoice_tagged, odr_integer,
8705       "tagged"},
8706       {-1, -1, -1, MyChoice_other, odr_boolean, "other"},
8707       {-1, -1, -1, -1, 0}
8708     };
8709
8710     if (o->direction == ODR_DECODE)
8711         *p = odr_malloc(o, sizeof(**p);
8712     else if (!*p)
8713         return optional &amp;&amp; odr_ok(o);
8714
8715     if (odr_choice(o, arm, &amp;(*p)->u, &amp;(*p)->which), name)
8716         return 1;
8717     *p = 0;
8718         return optional &amp;&amp; odr_ok(o);
8719 }
8720     </screen>
8721     <para>
8722      In some cases (say, a non-optional choice which is a member of a
8723      sequence), you can "embed" the union and its discriminator in the
8724      structure belonging to the enclosing type, and you won't need to
8725      fiddle with memory allocation to create a separate structure to
8726      wrap the discriminator and union.
8727     </para>
8728     <para>
8729      The corresponding function is somewhat nicer in the Sun XDR interface.
8730      Most of the complexity of this interface comes from the possibility of
8731      declaring sequence elements (including CHOICEs) optional.
8732     </para>
8733     <para>
8734      The ASN.1 specifications naturally requires that each member of a
8735      CHOICE have a distinct tag, so they can be told apart on decoding.
8736      Sometimes it can be useful to define a CHOICE that has multiple types
8737      that share the same tag. You'll need some other mechanism, perhaps
8738      keyed to the context of the CHOICE type. In effect, we would like to
8739      introduce a level of context-sensitiveness to our ASN.1 specification.
8740      When encoding an internal representation, we have no problem, as long
8741      as each CHOICE member has a distinct discriminator value. For
8742      decoding, we need a way to tell the choice function to look for a
8743      specific arm of the table. The function
8744     </para>
8745     <synopsis>
8746 void odr_choice_bias(ODR o, int what);
8747     </synopsis>
8748     <para>
8749      provides this functionality. When called, it leaves a notice for the next
8750      call to <function>odr_choice()</function> to be called on the decoding
8751      stream <literal>o</literal> that only the <literal>arm</literal> entry with
8752      a <literal>which</literal> field equal to <literal>what</literal>
8753      should be tried.
8754     </para>
8755     <para>
8756      The most important application (perhaps the only one, really) is in
8757      the definition of application-specific EXTERNAL encoders/decoders
8758      which will automatically decode an ANY member given the direct or
8759      indirect reference.
8760     </para>
8761    </sect2>
8762   </sect1>
8763   <sect1 id="odr.debugging">
8764    <title>Debugging</title>
8765    <para>
8766     The protocol modules are suffering somewhat from a lack of diagnostic
8767     tools at the moment. Specifically ways to pretty-print PDUs that
8768     aren't recognized by the system. We'll include something to this end
8769     in a not-too-distant release. In the meantime, what we do when we get
8770     packages we don't understand is to compile the ODR module with
8771     <literal>ODR_DEBUG</literal> defined. This causes the module to dump tracing
8772     information as it processes data units. With this output and the
8773     protocol specification (Z39.50), it is generally fairly easy to see
8774     what goes wrong.
8775    </para>
8776   </sect1>
8777  </chapter>
8778  <chapter id="comstack">
8779   <title>The COMSTACK Module</title>
8780   <sect1 id="comstack.synopsis">
8781    <title>Synopsis (blocking mode)</title>
8782    <programlisting><![CDATA[
8783     COMSTACK stack;
8784     char *buf = 0;
8785     int size = 0, length_incoming;
8786     char server_address_str[] = "localhost:9999";
8787     void *server_address_ip;
8788     int status;
8789
8790     char *protocol_package = "GET / HTTP/1.0\r\n\r\n";
8791     int protocol_package_length = strlen(protocol_package);
8792
8793     stack = cs_create(tcpip_type, 1, PROTO_HTTP);
8794     if (!stack) {
8795         perror("cs_create");  /* use perror() here since we have no stack yet */
8796         return -1;
8797     }
8798
8799     server_address_ip = cs_straddr(stack, server_address_str);
8800     if (!server_address_ip) {
8801         fprintf(stderr, "cs_straddr: address could not be resolved\n");
8802         return -1;
8803     }
8804
8805     status = cs_connect(stack, server_address_ip);
8806     if (status) {
8807         fprintf(stderr, "cs_connect: %s\n", cs_strerror(stack));
8808         return -1;
8809     }
8810
8811     status = cs_rcvconnect(stack);
8812     if (status) {
8813         fprintf(stderr, "cs_rcvconnect: %s\n", cs_strerror(stack));
8814         return -1;
8815     }
8816
8817     status = cs_put(stack, protocol_package, protocol_package_length);
8818     if (status) {
8819         fprintf(stderr, "cs_put: %s\n", cs_strerror(stack));
8820         return -1;
8821     }
8822
8823     /* Now get a response */
8824     length_incoming = cs_get(stack, &buf, &size);
8825     if (!length_incoming) {
8826         fprintf(stderr, "Connection closed\n");
8827         return -1;
8828     } else if (length_incoming < 0) {
8829         fprintf(stderr, "cs_get: %s\n", cs_strerror(stack));
8830         return -1;
8831     }
8832
8833     /* Print result */
8834     fwrite(buf, length_incoming, 1, stdout);
8835
8836     /* clean up */
8837     cs_close(stack);
8838     if (buf)
8839         xfree(buf);
8840     return 0;
8841 ]]>
8842    </programlisting>
8843
8844   </sect1>
8845   <sect1 id="comstack.introduction">
8846    <title>Introduction</title>
8847    <para>
8848     The &comstack;
8849     subsystem provides a transparent interface to different types of transport
8850     stacks for the exchange of BER-encoded data and HTTP packets.
8851     At present, the RFC1729 method (BER over TCP/IP), local UNIX socket and an
8852     experimental SSL stack are supported, but others may be added in time.
8853     The philosophy of the
8854     module is to provide a simple interface by hiding unused options and
8855     facilities of the underlying libraries. This is always done at the risk
8856     of losing generality, and it may prove that the interface will need
8857     extension later on.
8858    </para>
8859    <note>
8860     <para>
8861      There hasn't been interest in the XTImOSI stack for some years.
8862      Therefore, it is no longer supported.
8863      </para>
8864    </note>
8865    <para>
8866     The interface is implemented in such a fashion that only the
8867     sub-layers constructed to the transport methods that you wish to
8868     use in your application are linked in.
8869    </para>
8870    <para>
8871     You will note that even though simplicity was a goal in the design,
8872     the interface is still orders of magnitudes more complex than the
8873     transport systems found in many other packages. One reason is that
8874     the interface needs to support the somewhat different requirements of
8875     the different lower-layer communications stacks; another important
8876     reason is that the interface seeks to provide a more or less
8877     industrial-strength approach to asynchronous event-handling.
8878     When no function is allowed to block, things get more complex -
8879     particularly on the server side.
8880     We urge you to have a look at the demonstration client and server
8881     provided with the package. They are meant to be easily readable and
8882     instructive, while still being at least moderately useful.
8883    </para>
8884   </sect1>
8885   <sect1 id="comstack.common">
8886    <title>Common Functions</title>
8887    <sect2 id="comstack.managing.endpoints">
8888     <title>Managing Endpoints</title>
8889     <synopsis>
8890      COMSTACK cs_create(CS_TYPE type, int blocking, int protocol);
8891     </synopsis>
8892     <para>
8893      Creates an instance of the protocol stack - a communications endpoint.
8894      The <literal>type</literal> parameter determines the mode
8895      of communication. At present the following values are supported:
8896     </para>
8897     <variablelist>
8898      <varlistentry>
8899       <term><literal>tcpip_type</literal></term>
8900       <listitem><para>TCP/IP (BER over TCP/IP or HTTP over TCP/IP)
8901       </para></listitem>
8902      </varlistentry>
8903      <varlistentry>
8904       <term><literal>ssl_type</literal></term>
8905       <listitem><para>Secure Socket Layer (SSL). This COMSTACK
8906       is experimental and is not fully implemented. If
8907       HTTP is used, this effectively is HTTPS.
8908       </para></listitem>
8909      </varlistentry>
8910      <varlistentry>
8911       <term><literal>unix_type</literal></term>
8912       <listitem><para>Unix socket (unix only). Local Transfer via
8913       file socket. See <citerefentry><refentrytitle>unix</refentrytitle>
8914       <manvolnum>7</manvolnum></citerefentry>.
8915       </para></listitem>
8916      </varlistentry>
8917     </variablelist>
8918     <para>
8919      The <function>cs_create</function> function returns a null-pointer
8920      if a system error occurs.
8921      The <literal>blocking</literal> parameter should be one if
8922      you wish the association to operate in blocking mode, zero otherwise.
8923      The <literal>protocol</literal> field should be
8924      <literal>PROTO_Z3950</literal> or <literal>PROTO_HTTP</literal>.
8925      Protocol <literal>PROTO_SR</literal> is no longer supported.
8926     </para>
8927     <synopsis>
8928      void cs_close(COMSTACK handle);
8929     </synopsis>
8930     <para>
8931      Closes the connection (as elegantly as the lower layers will permit),
8932      and releases the resources pointed to by the
8933      <literal>handle</literal>
8934      parameter. The
8935      <literal>handle</literal>
8936      should not be referenced again after this call.
8937     </para>
8938     <note>
8939      <para>
8940       We really need a soft disconnect, don't we?
8941      </para>
8942     </note>
8943    </sect2>
8944    <sect2 id="comstack.data.exchange">
8945     <title>Data Exchange</title>
8946     <synopsis>
8947      int cs_put(COMSTACK handle, char *buf, int len);
8948     </synopsis>
8949     <para>
8950      Sends <literal>buf</literal> down the wire.
8951      In blocking mode, this function will return only when a full buffer has
8952      been written, or an error has occurred. In nonblocking mode, it's
8953      possible that the function will be unable to send the full buffer
8954      at once, which will be indicated by a return value of 1.
8955      The function will keep track of the number of octets already written; you
8956      should call it repeatedly with the same values of <literal>buf</literal>
8957      and <literal>len</literal>, until the buffer has been transmitted.
8958      When a full buffer has been sent, the function will return 0 for
8959      success. -1 indicates an error condition (see below).
8960     </para>
8961     <synopsis>
8962      int cs_get(COMSTACK handle, char **buf, int *size);
8963     </synopsis>
8964     <para>
8965      Receives a PDU or HTTP Response from the peer. Returns the number of
8966      bytes read.
8967      In nonblocking mode, it is possible that not all of the packet can be
8968      read at once. In this case, the function returns 1. To simplify the
8969      interface, the function is
8970      responsible for managing the size of the buffer. It will be reallocated
8971      if necessary to contain large packages, and will sometimes be moved
8972      around internally by the subsystem when partial packages are read. Before
8973      calling
8974      <function>cs_get</function>
8975      for the fist time, the buffer can be initialized to the null pointer,
8976      and the length should also be set to 0 - cs_get will perform a
8977      <function>malloc(2)</function>
8978      on the buffer for you. When a full buffer has been read, the size of
8979      the package is returned (which will always be greater than 1). -1
8980      indicates an error condition.
8981     </para>
8982     <para>
8983      See also the <function>cs_more()</function> function below.
8984     </para>
8985     <synopsis>
8986      int cs_more(COMSTACK handle);
8987     </synopsis>
8988     <para>
8989      The <function>cs_more()</function> function should be used in conjunction
8990      with <function>cs_get</function> and
8991      <function>select(2)</function>.
8992      The <function>cs_get()</function> function will sometimes
8993      (notably in the TCP/IP mode) read more than a single protocol package
8994      off the network. When this happens, the extra package is stored
8995      by the subsystem. After calling <function>cs_get()</function>, and before
8996      waiting for more input, You should always call
8997      <function>cs_more()</function>
8998      to check if there's a full protocol package already read. If
8999      <function>cs_more()</function>
9000      returns 1,
9001      <function>cs_get()</function>
9002      can be used to immediately fetch the new package. For the
9003      mOSI
9004      subsystem, the function should always return 0, but if you want your
9005      stuff to be protocol independent, you should use it.
9006     </para>
9007     <note>
9008      <para>
9009       The <function>cs_more()</function>
9010       function is required because the RFC1729-method
9011       does not provide a way of separating individual PDUs, short of
9012       partially decoding the BER. Some other implementations will carefully
9013       nibble at the packet by calling
9014       <function>read(2)</function>
9015       several times. This was felt to be too inefficient (or at least
9016       clumsy) - hence the call for this extra function.
9017      </para>
9018     </note>
9019     <synopsis>
9020      int cs_look(COMSTACK handle);
9021     </synopsis>
9022     <para>
9023      This function is useful when you're operating in nonblocking
9024      mode. Call it when
9025      <function>select(2)</function>
9026      tells you there's something happening on the line. It returns one of
9027      the following values:
9028     </para>
9029     <variablelist>
9030      <varlistentry>
9031       <term>CS_NONE</term>
9032       <listitem><para>
9033        No event is pending. The data found on the line was not a
9034        complete package.
9035       </para></listitem>
9036      </varlistentry>
9037      <varlistentry>
9038       <term>CS_CONNECT</term>
9039       <listitem><para>
9040        A response to your connect request has been received. Call
9041        <function>cs_rcvconnect</function>
9042        to process the event and to finalize the connection establishment.
9043       </para></listitem>
9044      </varlistentry>
9045      <varlistentry>
9046       <term>CS_DISCON</term>
9047       <listitem><para>
9048        The other side has closed the connection (or maybe sent a disconnect
9049        request - but do we care? Maybe later). Call
9050        <function>cs_close</function> to close your end of the association
9051        as well.
9052       </para></listitem>
9053      </varlistentry>
9054      <varlistentry>
9055       <term>CS_LISTEN</term>
9056       <listitem><para>
9057        A connect request has been received.
9058        Call <function>cs_listen</function> to process the event.
9059       </para></listitem>
9060      </varlistentry>
9061      <varlistentry>
9062       <term>CS_DATA</term>
9063       <listitem><para>
9064        There's data to be found on the line.
9065        Call <function>cs_get</function> to get it.
9066       </para></listitem>
9067      </varlistentry>
9068     </variablelist>
9069     <note>
9070      <para>
9071       You should be aware that even if
9072       <function>cs_look()</function>
9073       tells you that there's an event event pending, the corresponding
9074       function may still return and tell you there was nothing to be found.
9075       This means that only part of a package was available for reading. The
9076       same event will show up again, when more data has arrived.
9077      </para>
9078     </note>
9079     <synopsis>
9080      int cs_fileno(COMSTACK h);
9081     </synopsis>
9082     <para>
9083      Returns the file descriptor of the association. Use this when
9084      file-level operations on the endpoint are required
9085      (<function>select(2)</function> operations, specifically).
9086     </para>
9087    </sect2>
9088   </sect1>
9089   <sect1 id="comstack.client">
9090    <title>Client Side</title>
9091    <synopsis>
9092     int cs_connect(COMSTACK handle, void *address);
9093    </synopsis>
9094    <para>
9095     Initiate a connection with the target at <literal>address</literal>
9096     (more on addresses below). The function will return 0 on success, and 1 if
9097     the operation does not complete immediately (this will only
9098     happen on a nonblocking endpoint). In this case, use
9099     <function>cs_rcvconnect</function> to complete the operation,
9100     when <function>select(2)</function> or <function>poll(2)</function>
9101     reports input pending on the association.
9102    </para>
9103    <synopsis>
9104     int cs_rcvconnect(COMSTACK handle);
9105    </synopsis>
9106    <para>
9107     Complete a connect operation initiated by <function>cs_connect()</function>.
9108     It will return 0 on success; 1 if the operation has not yet completed (in
9109     this case, call the function again later); -1 if an error has occurred.
9110    </para>
9111   </sect1>
9112   <sect1 id="comstack.server">
9113    <title>Server Side</title>
9114    <para>
9115     To establish a server under the <application>inetd</application>
9116     server, you can use
9117    </para>
9118    <synopsis>
9119     COMSTACK cs_createbysocket(int socket, CS_TYPE type, int blocking,
9120                                int protocol);
9121    </synopsis>
9122    <para>
9123     The <literal>socket</literal> parameter is an established socket (when
9124     your application is invoked from <application>inetd</application>, the
9125     socket will typically be 0.
9126     The following parameters are identical to the ones for
9127     <function>cs_create</function>.
9128    </para>
9129    <synopsis>
9130     int cs_bind(COMSTACK handle, void *address, int mode)
9131    </synopsis>
9132    <para>
9133     Binds a local address to the endpoint. Read about addresses below. The
9134     <literal>mode</literal> parameter should be either
9135     <literal>CS_CLIENT</literal> or <literal>CS_SERVER</literal>.
9136    </para>
9137    <synopsis>
9138     int cs_listen(COMSTACK handle, char *addr, int *addrlen);
9139    </synopsis>
9140    <para>
9141     Call this to process incoming events on an endpoint that has been
9142     bound in listening mode. It will return 0 to indicate that the connect
9143     request has been received, 1 to signal a partial reception, and -1 to
9144     indicate an error condition.
9145    </para>
9146    <synopsis>
9147     COMSTACK cs_accept(COMSTACK handle);
9148    </synopsis>
9149    <para>
9150     This finalizes the server-side association establishment, after
9151     cs_listen has completed successfully. It returns a new connection
9152     endpoint, which represents the new association. The application will
9153     typically wish to fork off a process to handle the association at this
9154     point, and continue listen for new connections on the old
9155     <literal>handle</literal>.
9156    </para>
9157    <para>
9158     You can use the call
9159    </para>
9160    <synopsis>
9161     const char *cs_addrstr(COMSTACK);
9162    </synopsis>
9163    <para>
9164     on an established connection to retrieve the host-name of the remote host.
9165    </para>
9166    <note>
9167     <para>
9168      You may need to use this function with some care if your
9169      name server service is slow or unreliable
9170     </para>
9171    </note>
9172   </sect1>
9173   <sect1 id="comstack.addresses">
9174    <title>Addresses</title>
9175    <para>
9176     The low-level format of the addresses are different depending on the
9177     mode of communication you have chosen. A function is provided by each
9178     of the lower layers to map a user-friendly string-form address to the
9179     binary form required by the lower layers.
9180    </para>
9181    <synopsis>
9182     void *cs_straddr(COMSTACK handle, const char *str);
9183    </synopsis>
9184    <para>
9185     The format for TCP/IP and SSL addresses is:
9186    </para>
9187    <synopsis>
9188     &lt;host> [ ':' &lt;portnum> ]
9189    </synopsis>
9190    <para>
9191     The <literal>hostname</literal> can be either a domain name or an
9192     IP address. The port number, if omitted, defaults to 210.
9193    </para>
9194    <para>
9195     For TCP/IP and SSL, the special hostnames <literal>@</literal>,
9196     maps to <literal>IN6ADDR_ANY_INIT</literal> with
9197     IPV4 binding as well (bindv6only=0),
9198     The special hostname <literal>@4</literal> binds to
9199     <literal>INADDR_ANY</literal> (IPV4 only listener).
9200     The special hostname <literal>@6</literal> binds to
9201     <literal>IN6ADDR_ANY_INIT</literal> with bindv6only=1 (IPV6 only listener).
9202    </para>
9203    <para>
9204     For UNIX sockets, the format of an address is the socket filename.
9205    </para>
9206    <para>
9207     When a connection has been established, you can use
9208    </para>
9209    <synopsis>
9210     const char *cs_addrstr(COMSTACK h);
9211    </synopsis>
9212    <para>
9213     to retrieve the host name of the peer system. The function returns
9214     a pointer to a static area, which is overwritten on the next call
9215     to the function.
9216    </para>
9217    <para>
9218     A fairly recent addition to the &comstack; module is the utility
9219     function
9220    </para>
9221    <synopsis>
9222     COMSTACK cs_create_host (const char *str, int blocking, void **vp);
9223    </synopsis>
9224    <para>
9225     which is just a wrapper for <function>cs_create</function> and
9226     <function>cs_straddr</function>. The <parameter>str</parameter>
9227     is similar to that described for <function>cs_straddr</function>
9228     but with a prefix denoting the &comstack; type. Prefixes supported
9229     are <literal>tcp:</literal>, <literal>unix:</literal> and
9230     <literal>ssl:</literal> for TCP/IP, UNIX and SSL respectively.
9231     If no prefix is given, then TCP/IP is used.
9232     The <parameter>blocking</parameter> is passed to
9233     function <function>cs_create</function>. The third parameter
9234     <parameter>vp</parameter> is a pointer to &comstack; stack type
9235     specific values.
9236     Parameter <parameter>vp</parameter> is reserved for future use.
9237     Set it to <literal>NULL</literal>.
9238    </para>
9239   </sect1>
9240   <sect1 id="comstack.ssl">
9241    <title>SSL</title>
9242    <para>
9243     <synopsis>
9244      void *cs_get_ssl(COMSTACK cs);
9245     </synopsis>
9246     Returns the SSL handle, <literal>SSL *</literal> for comstack. If comstack
9247     is not of type SSL, NULL is returned.
9248    </para>
9249    <para>
9250     <synopsis>
9251      int cs_set_ssl_ctx(COMSTACK cs, void *ctx);
9252     </synopsis>
9253     Sets SSL context for comstack. The parameter is expected to be of type
9254     <literal>SSL_CTX *</literal>. This function should be called just
9255     after comstack has been created (before connect, bind, etc).
9256     This function returns 1 for success; 0 for failure.
9257    </para>
9258    <para>
9259     <synopsis>
9260      int cs_set_ssl_certificate_file(COMSTACK cs, const char *fname);
9261     </synopsis>
9262     Sets SSL certificate for comstack as a PEM file. This function
9263     returns 1 for success; 0 for failure.
9264    </para>
9265    <para>
9266     <synopsis>
9267      int cs_get_ssl_peer_certificate_x509(COMSTACK cs, char **buf, int *len);
9268     </synopsis>
9269     This function returns the peer certificate. If successful,
9270     <literal>*buf</literal> and <literal>*len</literal> holds
9271     X509 buffer and length respectively. Buffer should be freed
9272     with <literal>xfree</literal>. This function returns 1 for success;
9273     0 for failure.
9274    </para>
9275   </sect1>
9276   <sect1 id="comstack.diagnostics">
9277    <title>Diagnostics</title>
9278    <para>
9279     All functions return -1 if an error occurs. Typically, the functions
9280     will return 0 on success, but the data exchange functions
9281     (<function>cs_get</function>, <function>cs_put</function>,
9282     <function>cs_more</function>) follow special rules. Consult their
9283     descriptions.
9284    </para>
9285    <para>
9286     The error code for the COMSTACK can be retrieved using C macro
9287     <function>cs_errno</function> which will return one
9288     of the error codes <literal>CSYSERR</literal>,
9289     <literal>CSOUTSTATE</literal>,
9290     <literal>CSNODATA</literal>, ...
9291    </para>
9292    <synopsis>
9293     int cs_errno(COMSTACK handle);
9294    </synopsis>
9295    <para>
9296     You can the textual representation of the error code
9297     by using <function>cs_errmsg</function> - which
9298     works like <function>strerror(3)</function>
9299    </para>
9300    <synopsis>
9301     const char *cs_errmsg(int n);
9302    </synopsis>
9303    <para>
9304     It is also possible to get straight to the textual represenataion
9305     without the error code by using
9306     <function>cs_strerror</function>.
9307    </para>
9308    <synopsis>
9309     const char *cs_strerror(COMSTACK h);
9310    </synopsis>
9311   </sect1>
9312   <sect1 id="comstack.summary">
9313    <title>Summary and Synopsis</title>
9314    <synopsis><![CDATA[
9315     #include <yaz/comstack.h>
9316
9317     #include <yaz/tcpip.h>  /* this is for TCP/IP and SSL support */
9318     #include <yaz/unix.h>   /* this is for UNIX socket support */
9319
9320     COMSTACK cs_create(CS_TYPE type, int blocking, int protocol);
9321
9322     COMSTACK cs_createbysocket(int s, CS_TYPE type, int blocking,
9323                                int protocol);
9324     COMSTACK cs_create_host(const char *str, int blocking,
9325                             void **vp);
9326
9327     int cs_bind(COMSTACK handle, int mode);
9328
9329     int cs_connect(COMSTACK handle, void *address);
9330
9331     int cs_rcvconnect(COMSTACK handle);
9332
9333     int cs_listen(COMSTACK handle);
9334
9335     COMSTACK cs_accept(COMSTACK handle);
9336
9337     int cs_put(COMSTACK handle, char *buf, int len);
9338
9339     int cs_get(COMSTACK handle, char **buf, int *size);
9340
9341     int cs_more(COMSTACK handle);
9342
9343     void cs_close(COMSTACK handle);
9344
9345     int cs_look(COMSTACK handle);
9346
9347     void *cs_straddr(COMSTACK handle, const char *str);
9348
9349     const char *cs_addrstr(COMSTACK h);
9350 ]]>
9351    </synopsis>
9352   </sect1>
9353  </chapter>
9354  <chapter id="future">
9355   <title>Future Directions</title>
9356   <para>
9357    We have a new and better version of the front-end server on the drawing
9358    board. Resources and external commitments will govern when we'll be
9359    able to do something real with it. Features should include greater
9360    flexibility, greater support for access/resource control, and easy
9361    support for Explain (possibly with Zebra as an extra database engine).
9362   </para>
9363   <para>
9364    &yaz; is a BER toolkit and as such should support all protocols
9365    out there based on that. We'd like to see running ILL applications.
9366    It shouldn't be that hard. Another thing that would be interesting is
9367    LDAP. Maybe a generic framework for doing IR using both LDAP and
9368    Z39.50 transparently.
9369   </para>
9370   <para>
9371    The SOAP implementation is incomplete. In the future we hope
9372    to add more features to it. Perhaps make a WSDL/XML Schema compiler.
9373    The authors of libxml2 are already working on XML Schema / RelaxNG
9374    compilers so this may not be too hard.
9375   </para>
9376   <para>
9377    It would be neat to have a proper module mechanism for the Generic
9378    Frontend Server so that backend would be dynamically
9379    loaded (as shared objects / DLLs).
9380   </para>
9381   <para>
9382    Other than that, &yaz; generally moves in the directions which appear to
9383    make the most people happy (including ourselves, as prime users of the
9384    software). If there's something you'd like to see in here, then drop
9385    us a note and let's see what we can come up with.
9386   </para>
9387  </chapter>
9388  <reference id="reference">
9389   <title>Reference</title>
9390    <partintro id="reference-introduction">
9391     <para>
9392      The material in this chapter is drawn directly from the individual
9393      manual entries.
9394     </para>
9395    </partintro>
9396    &manref;
9397  </reference>
9398  <appendix id="list-oids">
9399   <title>List of Object Identifiers</title>
9400   <para>
9401    These is a list of object identifiers that are built into YAZ.
9402   </para>
9403   &std-oid-table;
9404  </appendix>
9405  <appendix id="bib1-diagnostics">
9406   <title>Bib-1 diagnostics</title>
9407   <para>
9408    List of Bib-1 diagnostics that are known to YAZ.
9409   </para>
9410   &bib1-diag-table;
9411  </appendix>
9412  <appendix id="sru-diagnostics">
9413   <title>SRU diagnostics</title>
9414   <para>
9415    List of SRU diagnostics that are known to YAZ.
9416   </para>
9417   &srw-diag-table;
9418  </appendix>
9419  <appendix id="license">
9420   <title>License</title>
9421   <sect1 id="license.indexdata">
9422    <title>Index Data Copyright</title>
9423    <para>
9424     Copyright &#xa9; &copyright-year; Index Data.
9425    </para>
9426    <para>
9427     All rights reserved.
9428    </para>
9429    <para>
9430     Redistribution and use in source and binary forms, with or without
9431     modification, are permitted provided that the following conditions are met:
9432    </para>
9433    <itemizedlist>
9434     <listitem>
9435      <para>
9436       Redistributions of source code must retain the above copyright
9437       notice, this list of conditions and the following disclaimer.
9438      </para>
9439     </listitem>
9440     <listitem>
9441      <para>
9442       Redistributions in binary form must reproduce the above copyright
9443       notice, this list of conditions and the following disclaimer in the
9444       documentation and/or other materials provided with the distribution.
9445      </para>
9446     </listitem>
9447     <listitem>
9448      <para>
9449       Neither the name of Index Data nor the names of its contributors
9450       may be used to endorse or promote products derived from this
9451       software without specific prior written permission.
9452       </para>
9453     </listitem>
9454    </itemizedlist>
9455    <para>
9456     THIS SOFTWARE IS PROVIDED BY INDEX DATA ``AS IS'' AND ANY
9457     EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
9458     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
9459     DISCLAIMED. IN NO EVENT SHALL INDEX DATA BE LIABLE FOR
9460     ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
9461     DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
9462     SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
9463     CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
9464     LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
9465     OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
9466     SUCH DAMAGE.
9467    </para>
9468   </sect1>
9469  </appendix>
9470  <appendix id="indexdata">
9471   <title>About Index Data</title>
9472   <para>
9473    Index Data is a consulting and software-development enterprise that
9474    specializes in library and information management systems. Our
9475    interests and expertise span a broad range of related fields, and one
9476    of our primary, long-term objectives is the development of a powerful
9477    information management
9478    system with open network interfaces and hyper-media capabilities.
9479   </para><para>
9480    We make this software available free of charge, on a fairly unrestrictive
9481    license; as a service to the networking community, and to further the
9482    development of quality software for open network communication.
9483   </para><para>
9484    We'll be happy to answer questions about the software, and about ourselves
9485    in general.
9486   </para>
9487   <para>
9488    <address>
9489     Index Data ApS
9490     <street>Amagerf&#xe6;lledvej 56</street>
9491     <postcode>2300 Copenhagen S</postcode>
9492     <country>Denmark</country>
9493     Email <email>info@indexdata.dk</email>
9494    </address>
9495   </para>
9496   <para>
9497    The Hacker's Jargon File has the following to say about the
9498    use of the
9499    prefix &quot;YA&quot; in the name of a software product.
9500   </para>
9501   <para>
9502    <citation>
9503     Yet Another. adj. 1. Of your own work: A
9504     humorous allusion often used in titles to acknowledge that the
9505     topic is not original, though the content is.  As in &quot;Yet Another
9506     AI Group&quot; or &quot;Yet Another Simulated Annealing Algorithm&quot;.
9507     2. Of
9508     others' work: Describes something of which there are already far
9509     too many.
9510    </citation>
9511   </para>
9512  </appendix>
9513  <appendix id="credits">
9514   <title>Credits</title>
9515   <para>
9516    This appendix lists individuals that have contributed in the development
9517    of &yaz;. Some have contributed with code, while others have provided bug
9518    fixes or suggestions. If we're missing somebody, of if you, for
9519    whatever reason, don't like to be listed here, let us know.
9520   </para>
9521   <itemizedlist>
9522    <listitem><para>
9523     Gary Anderson
9524    </para></listitem>
9525    <listitem><para>
9526     Dimitrios Andreadis
9527     </para></listitem>
9528    <listitem><para>
9529     Morten B&#xf8;geskov
9530    </para></listitem>
9531    <listitem><para>
9532     Rocco Carbone
9533    </para></listitem>
9534    <listitem><para>
9535     Matthew Carey
9536    </para></listitem>
9537    <listitem><para>
9538     Hans van Dalen
9539    </para></listitem>
9540    <listitem><para>
9541     Irina Dijour
9542    </para></listitem>
9543    <listitem><para>
9544     Larry E. Dixson
9545    </para></listitem>
9546    <listitem><para>
9547     Hans van den Dool
9548    </para></listitem>
9549    <listitem><para>
9550     Mads Bondo Dydensborg
9551    </para></listitem>
9552    <listitem><para>
9553     Franck Falcoz
9554    </para></listitem>
9555    <listitem><para>
9556     Kevin Gamiel
9557    </para></listitem>
9558    <listitem><para>
9559     Morten Garkier Hendriksen
9560    </para></listitem>
9561    <listitem><para>
9562     Morten Holmqvist
9563    </para></listitem>
9564    <listitem><para>
9565     Ian Ibbotson
9566    </para></listitem>
9567    <listitem><para>
9568     Shigeru Ishida
9569    </para></listitem>
9570    <listitem><para>
9571     Heiko Jansen
9572    </para></listitem>
9573    <listitem><para>
9574     David Johnson
9575    </para></listitem>
9576    <listitem><para>
9577     Oleg Kolobov
9578    </para></listitem>
9579    <listitem><para>
9580     Giannis Kosmas
9581    </para></listitem>
9582    <listitem><para>
9583     Kang-Jin Lee
9584    </para></listitem>
9585    <listitem><para>
9586     Pieter Van Lierop
9587    </para></listitem>
9588    <listitem><para>
9589     Stefan Lohrum
9590    </para></listitem>
9591    <listitem><para>
9592     Ronald van der Meer
9593    </para></listitem>
9594    <listitem><para>
9595     Thomas W. Place
9596    </para></listitem>
9597    <listitem><para>
9598     Peter Popovics
9599    </para></listitem>
9600    <listitem><para>
9601     Jacob Chr. Poulsen
9602    </para></listitem>
9603    <listitem><para>
9604     Ko van der Sloot
9605    </para></listitem>
9606    <listitem><para>
9607     Mike Taylor
9608    </para></listitem>
9609    <listitem><para>
9610     Rustam T. Usmanov
9611    </para></listitem>
9612    <listitem><para>
9613     Charles Woodfield
9614    </para></listitem>
9615    <listitem><para>
9616     Tom Andr&#xe9; &#xd8;verland
9617    </para></listitem>
9618   </itemizedlist>
9619  </appendix>
9620 </book>
9621
9622 <!-- Keep this comment at the end of the file
9623 Local variables:
9624 mode: nxml
9625 nxml-child-indent: 1
9626 End:
9627 -->