Stuff on SRW

diff --git a/doc/Makefile.am b/doc/Makefile.am
index cc736db..44d6dd9 100644 (file)
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,4 +1,4 @@
-## $Id: Makefile.am,v 1.37 2003-02-18 10:37:08 adam Exp $
+## $Id: Makefile.am,v 1.38 2003-02-21 00:24:26 adam Exp $

 
 docdir=$(datadir)/doc/@PACKAGE@
 
 
 docdir=$(datadir)/doc/@PACKAGE@
 

@@ -8,53 +8,19 @@ XMLFILES=yaz.xml.in introduction.xml installation.xml indexdata.xml \
  yaz-client-commands.xml
 
 HTMLFILES = \
  yaz-client-commands.xml
 
 HTMLFILES = \

-asn.external.html \
-asn.html \
-asn.oid.html \
-asn.pdu.html \
-asn.preparing.html \
-client.commands.html \
-client.html \
-client.invoking.html \
-client.searching.html \
-comstack.addresses.html \
-comstack.client.html \
-comstack.common.html \
-comstack.diagnostics.html \
-comstack.html \
-comstack.introduction.html \
-comstack.server.html \
-comstack.summary.html \
-credits.html \
-future.html \
-indexdata.html \
-installation.html \
-installation.unix.html \
-installation.win32.html \
-introduction.html \
-license.html \
-license.other.html \
-odr.debugging.html \
-odr.html \
-odr.programming.html \
-odr.use.html \
-server.backendfunctions.html \
-server.backend.html \
-server.frontend.html \
-server.html \
-server.invocation.html \
-server.main.html \
-tools.html \
-tools.nmem.html \
-tools.oid.html \
-yaz.html \
-zoom.events.html \
-zoom.html \
-zoom.options.html \
-zoom.query.html \
-zoom.records.html \
-zoom.resultsets.html \
-zoom.scan.html
+ asn.external.html asn.html asn.oid.html asn.pdu.html asn.preparing.html \
+ client.commands.html client.html client.invoking.html client.searching.html \
+ comstack.addresses.html comstack.client.html comstack.common.html \
+ comstack.diagnostics.html comstack.html comstack.introduction.html \
+ comstack.server.html comstack.summary.html credits.html future.html \
+ indexdata.html installation.html installation.unix.html \
+ installation.win32.html introduction.api.html introduction.html \
+ license.html license.other.html odr.debugging.html odr.html \
+ odr.programming.html odr.use.html server.backendfunctions.html \
+ server.backend.html server.frontend.html server.html server.invocation.html \
+ server.main.html tools.html tools.nmem.html tools.oid.html yaz.html \
+ zoom.events.html zoom.html zoom.options.html zoom.query.html \
+ zoom.records.html zoom.resultsets.html zoom.scan.html

 
 MANFILES=yaz-client.1 yaz-client-ssl.1 yaz-ztest.8 \
        yaz-ztest-ssl.8 yaz-config.1 yaz.7 zoomsh.1
 
 MANFILES=yaz-client.1 yaz-client-ssl.1 yaz-ztest.8 \
        yaz-ztest-ssl.8 yaz-config.1 yaz.7 zoomsh.1

diff --git a/doc/introduction.xml b/doc/introduction.xml
index 3ef6a0b..6710302 100644 (file)
--- a/doc/introduction.xml
+++ b/doc/introduction.xml
@@ -1,117 +1,270 @@
-<!-- $Id: introduction.xml,v 1.8 2002-08-17 07:55:51 adam Exp $ -->
+<!-- $Id: introduction.xml,v 1.9 2003-02-21 00:24:26 adam Exp $ -->

  <chapter id="introduction"><title>Introduction</title>
  <chapter id="introduction"><title>Introduction</title>

-  
-  <para>
-   The <ulink url="http://www.indexdata.dk/yaz/">&yaz;</ulink>
-   toolkit offers several different levels of access to the
-   <ulink url="http://www.loc.gov/z3950/agency/">ISO23950/Z39.50</ulink>
-   and <ulink url="http://www.nlc-bnc.ca/iso/ill/">ILL</ulink> protocols.
-   The level that you need to use depends on your requirements, and
-   the role (server or client) that you want to implement.
-   If you're developing a client application you should consider the
-   <link linkend="zoom">ZOOM</link> API.
-   It is, by far, the easiest way to develop clients in C.
-   Server implementers should consider the 
-   <link linkend="server">generic frontend server</link>.
-   None of those high-level APIs support the whole protocol, but
-   they do include most facilities used in existing Z39.50
-   applications.
-  </para>
+

   <para>
   <para>

-   If you're using 'exotic' functionality (meaning anything not included in
-   the high-level APIs), developing non-standard extensions to Z39.50 or you're
-   going to develop an ILL application you'll have to learn the lower
-   level APIs of &yaz;.
+   &yaz; is a C/C++ library for information retrieval applications
+   using the Z39.50/SRW protocols for information retrieval.

   </para>
   </para>

+

   <para>
   <para>

-   The basic low level modules, which are independent of the role
-   (client or server), consist of three primary interfaces:
-   
+   Properties of &yaz;:

    <itemizedlist>
    <itemizedlist>

-    <listitem><para>&asn;, which provides a C representation of the Z39.50
-      protocol packages (PDUs).
+    <listitem><para>
+      Fast operation. The C based BER encoders/decoders as well
+      as the server component of &yaz; is very fast.
+     </para></listitem>
+    <listitem><para>
+      Complete 
+      <ulink url="http://www.loc.gov/z3950/agency/">Z39.50</ulink>
+      version 3 support. All newer extensions
+      including Z39.50-2000 have been incorporated.
+     </para></listitem>
+    <listitem><para>
+      Supports 
+      <ulink url="http://www.loc.gov/z3950/agency/zing/srw/">SRW</ulink>
+      version 1.0 (over HTTP and HTTPS).
+     </para></listitem>
+    <listitem><para>
+      Includes BER encoders/decoders for the 
+      <ulink url="http://www.nlc-bnc.ca/iso/ill/">ISO ILL</ulink>
+      protocol.
+     </para></listitem>
+    <listitem><para>
+      Supports the following transports: BER over TCP/IP
+      (<ulink url="http://www.faqs.org/rfcs/rfc1729.html">RFC1729</ulink>),
+      BER over unix local socket, and 
+      <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616.html">HTTP
+       1.1</ulink>.
+     </para></listitem>
+    <listitem><para>
+      Secure Socket Layer support using
+      <ulink url="http://www.openssl.org/">OpenSSL</ulink>.
+      If enabled, &yaz; uses HTTPS transport (for SOAP) or
+      "Secure BER" (for Z39.50).
+     </para></listitem>
+    <listitem><para>
+      Offers 
+      <ulink url="http://zoom.z3950.org/">ZOOM</ulink>
+      C API implementing both Z39.50 and SRW.

      </para></listitem>
      </para></listitem>

-    <listitem><para>&odr;, which encodes and decodes the packages according
-      to the BER specification.
+    <listitem><para>
+      The &yaz; library offers a set of useful utilities
+      related to the protocols, such as MARC (ISO2709) parser,
+      CCL (ISO8777) parser, 
+      <ulink url="http://www.loc.gov/z3950/agency/zing/cql/">CQL</ulink>
+      parser, memory management routines, character set conversion.

      </para></listitem>
      </para></listitem>

-    <listitem><para>&comstack;, which exchanges the encoded packages with
-      a peer process over a network.
+    <listitem><para>
+      Portable code. &yaz; compiles out-of-the box on most Unixes and
+      on Windows using Microsoft Visual C++.
+     </para></listitem>
+    <listitem><para>
+      Liberal license that allows for commercial use of &yaz;.

      </para></listitem>
    </itemizedlist>
      </para></listitem>
    </itemizedlist>

-   
-   The &asn; module represents the ASN.1 definition of
-   the Z39.50 protocol. It establishes a set of type and
-   structure definitions, with one structure for each of the top-level
-   PDUs, and one structure or type for each of the contained ASN.1 types.
-   For primitive types, or other types that are defined by the ASN.1
-   standard itself (such as the EXTERNAL type), the C representation is
-   provided by the &odr; (Open Data Representation) subsystem.

   </para>
   </para>

-  <para>
-    &odr; is a basic mechanism for representing an
-   ASN.1 type in the C programming language, and for implementing BER
-   encoders and decoders for values of that type. The types defined in
-   the &asn; module generally have the prefix <literal>Z_</literal>, and
-   a suffix corresponding to the name of the type in the ASN.1
-   specification of the protocol (generally Z39.50-1995). In the case of
-   base types (those originating in the ASN.1 standard itself), the prefix
-   <literal>Odr_</literal> is sometimes seen. Either way, look for
-   the actual definition in either <filename>z-core.h</filename> (for the types
-   from the protocol), <filename>odr.h</filename> (for the primitive ASN.1
-   types).
-   The &asn; library also provides functions (which are, in turn,
-   defined using &odr; primitives) for encoding and decoding data values.
-   Their general form is

 
 

-   <funcsynopsis>
-    <funcprototype><funcdef>int <function>z_<replaceable>xxx</replaceable></function></funcdef>
-     <paramdef>ODR <parameter>o</parameter></paramdef>
-     <paramdef>Z_<replaceable>xxx</replaceable> **<parameter>p</parameter></paramdef>
-     <paramdef>int <parameter>optional</parameter></paramdef>
-     <paramdef>const char *<parameter>name</parameter></paramdef>
-    </funcprototype>
-   </funcsynopsis>
-   (note the lower-case &quot;z&quot; in the function name)
-  </para>
+  <sect1 id="introduction.reading"><title>Reading this Manual</title>
+   <para>Most implementors only need to read a fraction of the
+    material in thie manual, so a quick walkthrough of the chapters
+    is in order.
+   </para>
+   <itemizedlist>
+    <listitem>
+     <para>
+      <xref linkend="installation"/> contains installation 
+      instructions for &yaz;. You don't need reading this
+      if you expect to download &yaz; binaries.
+      However, the chapter contains information about how
+      to make <emphasis>your</emphasis> application link
+      with &yaz;.
+     </para>
+    </listitem>
+
+    <listitem>
+      <para>
+      <xref linkend="zoom"/> describes the ZOOM API of &yaz;.
+      This is definitely worth a read if you wish to develop a Z39.50/SRW
+     client.
+    </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      <xref linkend="zoom"/> describes the generic frontend server
+      and explains how to develop server Z39.50/SRW applications for &yaz;.
+     Obviously worth reading if you're to develop a server.
+    </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      <xref linkend="client"/> describes how to use the &yaz; Z39.50
+      client. If you're developer and wish to test your server
+      or a server from another party, you might find this chapter
+      useful.
+    </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      <xref linkend="asn"/> documents the most commonly used Z39.50
+      C data structures offered by the &yaz; API. Client
+      developers using ZOOM you do not need reading this. 
+      For the remaining client developers (not using ZOOM),
+      reading this chapter is a must.
+      Z39.50 server implementors should read this, unless you're 
+      developing a simple server (or SRW only).
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      <xref linkend="tools"/> contains sections for the various
+      tools offered by &yaz;. Scan through the material quickly
+      and see what's relevant to you! SRW implementors
+      might find the <link linkend="tools.cql">CQL</link> section
+      particularly useful.
+     </para>
+    </listitem>

 
 

-  <note>
+    <listitem>
+     <para>
+      <xref linkend="odr"/> goes through the details of the
+      ODR module which is the work horse that encodes and decodes
+      BER packages. Implementors using ZOOM only do not need reading this.
+      Most other Z39.50 implementors only need to read the first two
+      sections <link linkend="odr.introduction">Introduction</link>,
+      <link linkend="odr.use">Using ODR</link>.
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      <xref linkend="comstack"/> describes the network layer module
+      COMSTACK. Implementors using ZOOM or the generic frontend server
+      may skip this. Others, presumably, handling client/server
+     communication on their own should read this.
+     </para>
+    </listitem>
+
+   </itemizedlist>
+  </sect1>
+  <sect1 id="introduction.api"><title>The API</title>
+   

    <para>
    <para>

-    If you are using the premade definitions of the &asn; module, and you
-    are not adding new protocol of your own, the only parts of &odr; that you
-    need to worry about are documented in section 
-    <link linkend="odr-use">Using ODR</link>.
+    The <ulink url="http://www.indexdata.dk/yaz/">&yaz;</ulink>
+    toolkit offers several different levels of access to the
+    <ulink url="http://www.loc.gov/z3950/agency/">ISO23950/Z39.50</ulink>,
+    <ulink url="http://www.nlc-bnc.ca/iso/ill/">ILL</ulink> and
+    SRW protocols.
+    The level that you need to use depends on your requirements, and
+    the role (server or client) that you want to implement.
+    If you're developing a client application you should consider the
+    <link linkend="zoom">ZOOM</link> API.
+   It is, by far, the easiest way to develop clients in C.
+    Server implementers should consider the 
+    <link linkend="server">generic frontend server</link>.
+    None of those high-level APIs support the whole protocol, but
+    they do include most facilities used in existing Z39.50
+    applications.
+   </para>
+   <para>
+    If you're using 'exotic' functionality (meaning anything not included in
+    the high-level APIs), developing non-standard extensions to Z39.50 or
+    you're going to develop an ILL application you'll have to learn the lower
+    level APIs of &yaz;.

    </para>
    </para>

-  </note>
-

   <para>
   <para>

-   When you have created a BER-encoded buffer, you can use the &comstack;
-   subsystem to transmit (or receive) data over the network. The &comstack;
-   module provides simple functions for establishing a connection
-   (passively or actively, depending on the role of your application),
-   and for exchanging BER-encoded PDUs over that connection. When you
-   create a connection endpoint, you need to specify what transport to
-   use (TCP/IP, SSL or UNIX sockets).
-   For the remainder of the connection's lifetime, you don't have
-   to worry about the underlying transport protocol at all - the &comstack;
-   will ensure that the correct mechanism is used.
+    The basic low level modules, which are independent of the role
+    (client or server), consist of three primary interfaces:
+    
+    <itemizedlist>
+     <listitem><para>&asn;, which provides a C representation of the Z39.50
+       protocol packages (PDUs).
+      </para></listitem>
+     <listitem><para>&odr;, which encodes and decodes the packages according
+       to the BER specification.
+      </para></listitem>
+     <listitem><para>&comstack;, which exchanges the encoded packages with
+       a peer process over a network.
+      </para></listitem>
+    </itemizedlist>
+    
+    The &asn; module represents the ASN.1 definition of
+    the Z39.50 protocol. It establishes a set of type and
+    structure definitions, with one structure for each of the top-level
+    PDUs, and one structure or type for each of the contained ASN.1 types.
+    For primitive types, or other types that are defined by the ASN.1
+    standard itself (such as the EXTERNAL type), the C representation is
+    provided by the &odr; (Open Data Representation) subsystem.

   </para>
   </para>

+   <para>
+     &odr; is a basic mechanism for representing an
+    ASN.1 type in the C programming language, and for implementing BER
+    encoders and decoders for values of that type. The types defined in
+    the &asn; module generally have the prefix <literal>Z_</literal>, and
+    a suffix corresponding to the name of the type in the ASN.1
+    specification of the protocol (generally Z39.50-1995). In the case of
+    base types (those originating in the ASN.1 standard itself), the prefix
+    <literal>Odr_</literal> is sometimes seen. Either way, look for
+    the actual definition in either <filename>z-core.h</filename> (for the types
+    from the protocol), <filename>odr.h</filename> (for the primitive ASN.1
+    types).
+    The &asn; library also provides functions (which are, in turn,
+    defined using &odr; primitives) for encoding and decoding data values.
+    Their general form is
+    
+    <funcsynopsis>
+     <funcprototype><funcdef>int <function>z_<replaceable>xxx</replaceable></function></funcdef>
+      <paramdef>ODR <parameter>o</parameter></paramdef>
+      <paramdef>Z_<replaceable>xxx</replaceable> **<parameter>p</parameter></paramdef>
+      <paramdef>int <parameter>optional</parameter></paramdef>
+      <paramdef>const char *<parameter>name</parameter></paramdef>
+     </funcprototype>
+    </funcsynopsis>
+    (note the lower-case &quot;z&quot; in the function name)
+   </para>
+   
+   <note>
+    <para>
+     If you are using the premade definitions of the &asn; module, and you
+     are not adding new protocol of your own, the only parts of &odr; that you
+     need to worry about are documented in section 
+     <link linkend="odr-use">Using ODR</link>.
+    </para>
+   </note>
+   

   <para>
   <para>

-   We call the combined interfaces to &odr;, &asn;, and &comstack; the service
-   level API. It's the API that most closely models the Z39.50
+    When you have created a BER-encoded buffer, you can use the &comstack;
+    subsystem to transmit (or receive) data over the network. The &comstack;
+    module provides simple functions for establishing a connection
+    (passively or actively, depending on the role of your application),
+    and for exchanging BER-encoded PDUs over that connection. When you
+    create a connection endpoint, you need to specify what transport to
+    use (TCP/IP, SSL or UNIX sockets).
+    For the remainder of the connection's lifetime, you don't have
+   to worry about the underlying transport protocol at all - the &comstack;
+    will ensure that the correct mechanism is used.
+   </para>
+   <para>
+    We call the combined interfaces to &odr;, &asn;, and &comstack; the service
+    level API. It's the API that most closely models the Z39.50

    service/protocol definition, and it provides unlimited access to all
    service/protocol definition, and it provides unlimited access to all

-   fields and facilities of the protocol definitions.
-  </para>
-  <para>
-   The reason that the &yaz; service-level API is a conglomerate of the
+    fields and facilities of the protocol definitions.
+   </para>
+   <para>
+    The reason that the &yaz; service-level API is a conglomerate of the

    APIs from three different submodules is twofold. First, we wanted to allow
    APIs from three different submodules is twofold. First, we wanted to allow

-   the user a choice of different options for each major task. For instance,
-   if you don't like the protocol API provided by &odr;/&asn;, you
-   can use SNACC or BERUtils instead, and still have the benefits of the
-   transparent transport approach of the &comstack; module. Secondly,
-   we realize that you may have to fit the toolkit into an existing
-   event-processing structure, in a way that is incompatible with
-   the &comstack; interface or some other part of &yaz;.
-  </para>
+    the user a choice of different options for each major task. For instance,
+    if you don't like the protocol API provided by &odr;/&asn;, you
+    can use SNACC or BERUtils instead, and still have the benefits of the
+    transparent transport approach of the &comstack; module. Secondly,
+    we realize that you may have to fit the toolkit into an existing
+    event-processing structure, in a way that is incompatible with
+    the &comstack; interface or some other part of &yaz;.
+   </para>
+  </sect1>

  </chapter>
 
  <!-- Keep this comment at the end of the file
  </chapter>
 
  <!-- Keep this comment at the end of the file

diff --git a/doc/yaz.xml.in b/doc/yaz.xml.in
index 3b2c0e6..718d034 100644 (file)
--- a/doc/yaz.xml.in
+++ b/doc/yaz.xml.in
@@ -24,11 +24,12 @@
      <!ENTITY comstack "<acronym>COMSTACK</acronym>">
      <!ENTITY zoom "<acronym>ZOOM</acronym>">
 ]>
      <!ENTITY comstack "<acronym>COMSTACK</acronym>">
      <!ENTITY zoom "<acronym>ZOOM</acronym>">
 ]>

-<!-- $Id: yaz.xml.in,v 1.7 2003-01-22 14:39:16 adam Exp $ -->
+<!-- $Id: yaz.xml.in,v 1.8 2003-02-21 00:24:26 adam Exp $ -->

 <book id="yaz">
  <bookinfo>
   <title>YAZ User&apos;s Guide and Reference</title>
   <author><firstname>Sebastian</firstname><surname>Hammer</surname></author>
 <book id="yaz">
  <bookinfo>
   <title>YAZ User&apos;s Guide and Reference</title>
   <author><firstname>Sebastian</firstname><surname>Hammer</surname></author>

+  <author><firstname>Adam</firstname><surname>Dickmeiss</surname></author>

   <editor><firstname>Adam</firstname><surname>Dickmeiss</surname></editor>
   <copyright>
    <year>1995-2003</year>
   <editor><firstname>Adam</firstname><surname>Dickmeiss</surname></editor>
   <copyright>
    <year>1995-2003</year>

@@ -37,7 +38,7 @@
   <abstract><simpara>
     This document is the programmer's guide and reference to the &yaz;
     package version @VERSION@. &yaz; is a compact toolkit that provides
   <abstract><simpara>
     This document is the programmer's guide and reference to the &yaz;
     package version @VERSION@. &yaz; is a compact toolkit that provides

-    access to the Z39.50 protocol, as well as a set of higher-level
+    access to the Z39.50 and SRW protocols, as well as a set of higher-level

     tools for implementing the server and client roles, respectively.
     The documentation can be used on its own, or as a reference when
     looking at the example applications provided with the package.
     tools for implementing the server and client roles, respectively.
     The documentation can be used on its own, or as a reference when
     looking at the example applications provided with the package.

diff --git a/doc/zoom.xml b/doc/zoom.xml
index 549e16d..a9d97ae 100644 (file)
--- a/doc/zoom.xml
+++ b/doc/zoom.xml
@@ -1,5 +1,5 @@
-<!-- $Id: zoom.xml,v 1.21 2002-12-09 23:32:29 adam Exp $ -->
- <chapter id="zoom"><title>Building clients with ZOOM</title>
+<!-- $Id: zoom.xml,v 1.22 2003-02-21 00:24:26 adam Exp $ -->
+ <chapter id="zoom"><title>ZOOM</title>

   <para>
     &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is
    an initiative started by Mike Taylor (Mike is from the UK, which
   <para>
     &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is
    an initiative started by Mike Taylor (Mike is from the UK, which

@@ -7,6 +7,15 @@
    provide a common Z39.50 client API not bound to a particular
    programming language or toolkit.
   </para>
    provide a common Z39.50 client API not bound to a particular
    programming language or toolkit.
   </para>

+
+  <note>
+   <para>
+    A recent addition to &yaz; is SRW support. You can now make
+    SRW ZOOM connections by specifying a new scheme for the
+    host name for a connection.
+   </para>
+  </note>
+

   <para>
    The lack of a simple Z39.50 client API for &yaz; has become more
    and more apparent over time. So when the first &zoom; specification
   <para>
    The lack of a simple Z39.50 client API for &yaz; has become more
    and more apparent over time. So when the first &zoom; specification

@@ -75,6 +84,11 @@
     slash, the following part specifies a database for the connection.
    </para>
    <para>
     slash, the following part specifies a database for the connection.
    </para>
    <para>

+    You can prefix the host with a scheme followed by colon. The
+    default scheme is <literal>tcp</literal> (Z39.50 protocol).
+    The scheme <literal>http</literal> selects SRW over HTTP.
+   </para>
+   <para>

     Connection objects should be destroyed using the function
     <function>ZOOM_connection_destroy</function>.
    </para>
     Connection objects should be destroyed using the function
     <function>ZOOM_connection_destroy</function>.
    </para>

@@ -179,7 +193,7 @@
     of <function>ZOOM_connection_error</function> that is capable of
     returning name of diagnostic set in <parameter>dset</parameter>.
    </para>
     of <function>ZOOM_connection_error</function> that is capable of
     returning name of diagnostic set in <parameter>dset</parameter>.
    </para>

-   <sect2><title>Protocol behavior</title>
+   <sect2><title>Z39.50 Protocol behavior</title>

     <para>
      The calls <function>ZOOM_connection_new</function> and
      <function>ZOOM_connection_connect</function> establishes a TCP/IP
     <para>
      The calls <function>ZOOM_connection_new</function> and
      <function>ZOOM_connection_connect</function> establishes a TCP/IP

@@ -217,6 +231,20 @@
      API cannot tell the outcome (yet).
     </para>
     </sect2>
      API cannot tell the outcome (yet).
     </para>
     </sect2>

+   <sect2><title>SRW Protocol behavior</title>
+    <para>
+     The SRW protocol doesn't feature an Init Request, so
+     the connection phase merely establishes a TCP/IP connection
+     with the SOAP service.
+    </para>
+    <para>None of the ZOOM connection options
+     affect SRW and they are ignored. However, future versions
+     of &yaz; might honor <literal>implementationName</literal> and
+     put that as part of User-Agent header for HTTP requests.
+     The <literal>charset</literal>, and <literal>lang</literal>
+     might also affect HTTP headers in future releases.
+    </para>
+   </sect2>

   </sect1>
   <sect1 id="zoom.query"><title>Queries</title>
    <para>
   </sect1>
   <sect1 id="zoom.query"><title>Queries</title>
    <para>

@@ -229,6 +257,8 @@
 
      int ZOOM_query_prefix(ZOOM_query q, const char *str);
 
 
      int ZOOM_query_prefix(ZOOM_query q, const char *str);
 

+     int ZOOM_query_cql(ZOOM_query s, const char *str);
+

      int ZOOM_query_sortby(ZOOM_query q, const char *criteria);
    </synopsis>
    <para>
      int ZOOM_query_sortby(ZOOM_query q, const char *criteria);
    </synopsis>
    <para>

@@ -236,8 +266,10 @@
     and destroy them by calling <function>ZOOM_query_destroy</function>.
     RPN-queries can be specified in <link linkend="PQF">PQF</link>
     notation by using the
     and destroy them by calling <function>ZOOM_query_destroy</function>.
     RPN-queries can be specified in <link linkend="PQF">PQF</link>
     notation by using the

-    function <function>ZOOM_query_prefix</function>. More
-    query types will be added later, such as
+    function <function>ZOOM_query_prefix</function>.
+    The <function>ZOOM_query_cql</function> specifies a CQL
+    query to be sent to the server/target.
+    More query types will be added in future versions of &yaz;, such as

     <link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
     etc. In addition to a search, a sort criteria may be set. Function
     <function>ZOOM_query_sortby</function> specifies a 
     <link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
     etc. In addition to a search, a sort criteria may be set. Function
     <function>ZOOM_query_sortby</function> specifies a 

@@ -368,7 +400,7 @@
     </tgroup>
    </table>
    <sect2>
     </tgroup>
    </table>
    <sect2>

-    <title>Protocol behavior</title>
+    <title>Z39.50 Protocol behavior</title>

     <para>
      The creation of a result set involves at least a SearchRequest
      - SearchResponse protocol handshake. Following that, if a sort
     <para>
      The creation of a result set involves at least a SearchRequest
      - SearchResponse protocol handshake. Following that, if a sort

@@ -418,6 +450,47 @@
      to specify one elementSetName option rather than three.
      </para>
    </sect2>
      to specify one elementSetName option rather than three.
      </para>
    </sect2>

+   <sect2>
+    <title>SRW Protocol behavior</title>
+    <para>
+     Current version of &yaz; does not take advantage of a result set id
+     returned by the SRW server. Future versions might do, however.
+     Since, the ZOOM driver does not save result set IDs any
+     present (retrieval) is transformed to a SRW SearchRetrieveRequest
+     with same query but, possibly, different offsets.
+    </para>
+    <para>
+     Option <literal>schema</literal> specifies SRW schema
+     for retrieval. However, options <literal>elementSetName</literal> and
+     <literal>preferredRecordSyntax</literal> are ignored.
+    </para>
+    <para>
+     Options <literal>start</literal> and <literal>count</literal> 
+     are supported by SRW.
+     The remaining options
+     <literal>piggyback</literal>, 
+     <literal>smallSetUpperBound</literal>, 
+     <literal>largeSetLowerBound</literal>, 
+     <literal>mediumSetPresentNumber</literal>, 
+     <literal>mediumSetElementSetName</literal>,
+      <literal>smallSetElementSetName</literal> are
+     unsupported.
+    </para>
+    <para>
+     SRW supports CQL queries, <emphasis>not</emphasis> PQF.
+     If PQF is used, however, the PQF query is transferred anyway
+     using non-standard element <literal>pQuery</literal> in
+     SRW SearchRetrieveRequest.
+    </para>
+    <para>
+     Unfortunately, SRW does not define a database setting. Hence,
+     <literal>databaseName</literal> is unsupported and ignored.
+     However, the path part in host parameter for functions 
+     <function>ZOOM_connecton_new</function> and
+     <function>ZOOM_connection_connect</function> acts as a
+     database (at least for the &yaz; SRW server).
+    </para>
+   </sect2>

   </sect1>
   <sect1 id="zoom.records"><title>Records</title>
    <para>
   </sect1>
   <sect1 id="zoom.records"><title>Records</title>
    <para>

@@ -508,7 +581,7 @@
       </varlistentry>
     </variablelist>
    </para>
       </varlistentry>
     </variablelist>
    </para>

-   <sect2><title>Protocol behavior</title>
+   <sect2><title>Z39.50 Protocol behavior</title>

     <para>
      The functions <function>ZOOM_resultset_record</function> and
      <function>ZOOM_resultset_records</function> inspects the client-side
     <para>
      The functions <function>ZOOM_resultset_record</function> and
      <function>ZOOM_resultset_records</function> inspects the client-side

@@ -527,6 +600,13 @@
      <emphasis>now</emphasis>.
     </para>
    </sect2>
      <emphasis>now</emphasis>.
     </para>
    </sect2>

+   <sect2><title>SRW Protocol behavior</title>
+    <para>
+     The ZOOM driver for SRW treats records returned by a SRW server
+     as if they where Z39.50 records with transfer syntax XML and
+     no element set name or database name.
+    </para>
+   </sect2>

   </sect1>
   <sect1 id="zoom.scan"><title>Scan</title>
    <para>
   </sect1>
   <sect1 id="zoom.scan"><title>Scan</title>
    <para>

@@ -535,6 +615,12 @@
     is the <literal>ZOOM_scanset</literal> which is a set of terms
     returned by a target.
    </para>
     is the <literal>ZOOM_scanset</literal> which is a set of terms
     returned by a target.
    </para>

+
+   <para>
+    The Scan interface is Z39.50 only. SRW version 1.0 does not
+    support this.
+   </para>
+

    <synopsis>
     ZOOM_scanset ZOOM_connection_scan (ZOOM_connection c,
                                        const char *startterm);
    <synopsis>
     ZOOM_scanset ZOOM_connection_scan (ZOOM_connection c,
                                        const char *startterm);