Update doc WRT json render

[yaz-moved-to-github.git] / doc / zoom.xml

diff --git a/doc/zoom.xml b/doc/zoom.xml
index 87089ee..d1ccf8e 100644 (file)
--- a/doc/zoom.xml
+++ b/doc/zoom.xml
@@ -5,11 +5,10 @@ ZOOM_connection_errmsg(c)
 ZOOM_connection_addinfo(c)
 ZOOM_connection_addinfo(c)
 ZOOM_connection_diagset(c);
 ZOOM_connection_addinfo(c)
 ZOOM_connection_addinfo(c)
 ZOOM_connection_diagset(c);

+ZOOM_connection_save_apdu_wrbuf

 ZOOM_diag_str(error)
 ZOOM_resultset_record_immediate(s, pos)
 ZOOM_resultset_cache_reset(r)
 ZOOM_diag_str(error)
 ZOOM_resultset_record_immediate(s, pos)
 ZOOM_resultset_cache_reset(r)

-ZOOM_resultset_sort(r, sort_type, sort_spec)
-ZOOM_resultset_sort1(r, sort_type, sort_spec)

 ZOOM_options_set_callback(opt, function, handle)
 ZOOM_options_create_with_parent2(parent1, parent2)
 ZOOM_options_getl(opt, name, len)
 ZOOM_options_set_callback(opt, function, handle)
 ZOOM_options_create_with_parent2(parent1, parent2)
 ZOOM_options_getl(opt, name, len)

@@ -17,10 +16,7 @@ ZOOM_options_setl(opt, name, value, len)
 ZOOM_options_get_bool(opt, name, defa)
 ZOOM_options_get_int(opt, name, defa)
 ZOOM_options_set_int(opt, name, value)
 ZOOM_options_get_bool(opt, name, defa)
 ZOOM_options_get_int(opt, name, defa)
 ZOOM_options_set_int(opt, name, value)

-ZOOM_connection_scan1 (ZOOM_connection c, ZOOM_query startterm)
-ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)

 -->
 -->

-<!-- $Id: zoom.xml,v 1.64 2007-09-08 06:17:45 adam Exp $ -->

  <chapter id="zoom"><title>ZOOM</title>
   <para>
     &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is
  <chapter id="zoom"><title>ZOOM</title>
   <para>
     &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is

@@ -30,22 +26,26 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
    programming language or toolkit.
   </para>
 
    programming language or toolkit.
   </para>
 

-  <note>
-   <para>
-    A recent addition to &yaz; is SRU support. You can now make
-    SRU ZOOM connections by specifying scheme <literal>http://</literal>
-    for the hostname for a connection.  The dialect of SRU used is
-    specified by the value of the connection's <literal>sru</literal>
-    option, which may be SRU over HTTP GET (<literal>get</literal>),
-    SRU over HTTP POST (<literal>post</literal>) or SRW (SRU over
-    SOAP) (<literal>soap</literal>).  Using the facility for embedding
-    options in target strings, a connection can be forced to use SRU
-    rather the SRW (the default) by prefixing the target string with
-    <literal>sru=get,</literal>, like this:
+  <para>
+    From YAZ version 2.1.12, <ulink url="&url.sru;">SRU</ulink> is supported.
+    You can make SRU ZOOM connections by specifying scheme
+    <literal>http://</literal> for the hostname for a connection.
+    The dialect of SRU used is specified by the value of the
+    connection's <literal>sru</literal> option, which may be SRU over
+    HTTP GET (<literal>get</literal>),
+    SRU over HTTP POST (<literal>post</literal>), (SRU over
+    SOAP) (<literal>soap</literal>) or <literal>solr</literal>
+    (<ulink url="&url.solr;">Solr</ulink> Web Service).
+    Using the facility for embedding options in target strings, a
+    connection can be forced to use SRU rather the SRW (the default) by
+    prefixing the target string with <literal>sru=get,</literal>, like this:

     <literal>sru=get,http://sru.miketaylor.org.uk:80/sru.pl</literal>
     <literal>sru=get,http://sru.miketaylor.org.uk:80/sru.pl</literal>

-   </para>
-  </note>
-
+  </para>
+  <para>
+   <ulink url="&url.solr;">Solr</ulink>  protocol support was added to
+   YAZ in version 4.1.0, as a dialect of a SRU protocol, since both are
+   HTTP based protocols.
+  </para>

   <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

@@ -60,14 +60,14 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
    <ulink url="&url.zoom;">ZOOM web-site</ulink> for
    more information.
   </para>
    <ulink url="&url.zoom;">ZOOM web-site</ulink> for
    more information.
   </para>

-  
+

   <para>
    In order to fully understand this chapter you should read and
    try the example programs <literal>zoomtst1.c</literal>,
    <literal>zoomtst2.c</literal>, .. in the <literal>zoom</literal>
    directory.
   </para>
   <para>
    In order to fully understand this chapter you should read and
    try the example programs <literal>zoomtst1.c</literal>,
    <literal>zoomtst2.c</literal>, .. in the <literal>zoom</literal>
    directory.
   </para>

-  
+

   <para>
    The C language misses features found in object oriented languages
    such as C++, Java, etc. For example, you'll have to manually,
   <para>
    The C language misses features found in object oriented languages
    such as C++, Java, etc. For example, you'll have to manually,

@@ -84,29 +84,29 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
    protocol.
   </para>
   <sect1 id="zoom-connections"><title>Connections</title>
    protocol.
   </para>
   <sect1 id="zoom-connections"><title>Connections</title>

-   
+

    <para>The Connection object is a session with a target.
    </para>
    <synopsis>
     #include &lt;yaz/zoom.h>
    <para>The Connection object is a session with a target.
    </para>
    <synopsis>
     #include &lt;yaz/zoom.h>

-    
-    ZOOM_connection ZOOM_connection_new (const char *host, int portnum);
-    
-    ZOOM_connection ZOOM_connection_create (ZOOM_options options);
-    
+
+    ZOOM_connection ZOOM_connection_new(const char *host, int portnum);
+
+    ZOOM_connection ZOOM_connection_create(ZOOM_options options);
+

     void ZOOM_connection_connect(ZOOM_connection c, const char *host,
                                  int portnum);
     void ZOOM_connection_connect(ZOOM_connection c, const char *host,
                                  int portnum);

-    void ZOOM_connection_destroy (ZOOM_connection c);
+    void ZOOM_connection_destroy(ZOOM_connection c);

    </synopsis>
    <para>
     Connection objects are created with either function
    </synopsis>
    <para>
     Connection objects are created with either function

-    <function>ZOOM_connection_new</function> or 
+    <function>ZOOM_connection_new</function> or

     <function>ZOOM_connection_create</function>.
     The former creates and automatically attempts to establish a network
     connection with the target. The latter doesn't establish
     a connection immediately, thus allowing you to specify options
     before establishing network connection using the function
     <function>ZOOM_connection_create</function>.
     The former creates and automatically attempts to establish a network
     connection with the target. The latter doesn't establish
     a connection immediately, thus allowing you to specify options
     before establishing network connection using the function

-    <function>ZOOM_connection_connect</function>. 
+    <function>ZOOM_connection_connect</function>.

     If the port number, <literal>portnum</literal>, is zero, the
     <literal>host</literal> is consulted for a port specification.
     If no port is given, 210 is used. A colon denotes the beginning of
     If the port number, <literal>portnum</literal>, is zero, the
     <literal>host</literal> is consulted for a port specification.
     If no port is given, 210 is used. A colon denotes the beginning of

@@ -116,7 +116,8 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
    <para>
     You can prefix the host with a scheme followed by colon. The
     default scheme is <literal>tcp</literal> (Z39.50 protocol).
    <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 SRU over HTTP.
+    The scheme <literal>http</literal> selects SRU/get over HTTP by default,
+    but can overridded to use SRU/post, SRW and the Solr protocol.

    </para>
    <para>
     You can prefix the scheme-qualified host-string with one or more
    </para>
    <para>
     You can prefix the scheme-qualified host-string with one or more

@@ -151,7 +152,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
     The functions <function>ZOOM_connection_option_set</function> and
     <function>ZOOM_connection_option_setl</function> allows you to
     set an option given by <parameter>key</parameter> to the value
     The functions <function>ZOOM_connection_option_set</function> and
     <function>ZOOM_connection_option_setl</function> allows you to
     set an option given by <parameter>key</parameter> to the value

-    <parameter>value</parameter> for the connection. 
+    <parameter>value</parameter> for the connection.

     For <function>ZOOM_connection_option_set</function>, the
     value is assumed to be a 0-terminated string. Function
     <function>ZOOM_connection_option_setl</function> specifies a
     For <function>ZOOM_connection_option_set</function>, the
     value is assumed to be a 0-terminated string. Function
     <function>ZOOM_connection_option_setl</function> specifies a

@@ -189,14 +190,25 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
         password</entry><entry>Authentication password.
        </entry><entry>none</entry></row>
       <row><entry>
         password</entry><entry>Authentication password.
        </entry><entry>none</entry></row>
       <row><entry>

+        authenticationMode</entry><entry>How authentication is encoded.
+       </entry><entry>basic</entry></row>
+      <row><entry>

         host</entry><entry>Target host. This setting is "read-only".
         It's automatically set internally when connecting to a target.
        </entry><entry>none</entry></row>
       <row><entry>
         host</entry><entry>Target host. This setting is "read-only".
         It's automatically set internally when connecting to a target.
        </entry><entry>none</entry></row>
       <row><entry>

-        proxy</entry><entry>Proxy host
+        proxy</entry><entry>Proxy host. If set, the logical host
+       is encoded in the otherInfo area of the Z39.50 Init PDU
+       with OID 1.2.840.10003.10.1000.81.1.
+       </entry><entry>none</entry></row>
+      <row><entry>
+        clientIP</entry><entry>Client IP. If set, is
+       encoded in the otherInfo area of a Z39.50 PDU with OID
+       1.2.840.10003.10.1000.81.3. Holds the original IP addreses
+       of a client. Is used of ZOOM is used in a gateway of some sort.

        </entry><entry>none</entry></row>
       <row><entry>
        </entry><entry>none</entry></row>
       <row><entry>

-        async</entry><entry>If true (1) the connection operates in 
+        async</entry><entry>If true (1) the connection operates in

         asynchronous operation which means that all calls are non-blocking
         except
         <link linkend="zoom.events"><function>ZOOM_event</function></link>.
         asynchronous operation which means that all calls are non-blocking
         except
         <link linkend="zoom.events"><function>ZOOM_event</function></link>.

@@ -267,6 +279,12 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
        discover whether the server claims to support the specified
        operations.
        </entry><entry>none</entry></row>
        discover whether the server claims to support the specified
        operations.
        </entry><entry>none</entry></row>

+      <row>
+       <entry>sru</entry><entry>
+       SRU/Solr transport type. Must be either <literal>soap</literal>,
+       <literal>get</literal>, <literal>post</literal>, or
+       <literal>solr</literal>.
+        </entry><entry>soap</entry></row>

       <row><entry>
         sru_version</entry><entry>
        SRU/SRW version. Should be <literal>1.1</literal>, or
       <row><entry>
         sru_version</entry><entry>
        SRU/SRW version. Should be <literal>1.1</literal>, or

@@ -274,21 +292,53 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
        to offer (highest version). And following connect (in fact
        first operation), holds the negotiated version with the server
        (same or lower version).
        to offer (highest version). And following connect (in fact
        first operation), holds the negotiated version with the server
        (same or lower version).

-       </entry><entry>1.1</entry></row>
+       </entry><entry>1.2</entry></row>
+      <row><entry>
+        facets</entry><entry>
+       A FacetList is comma-separated list of facet, which is defined
+       as <literal>AttributeList</literal>  and a optional FacetTerm
+       (a Term and a frequency). On request the terms is missing.
+       On response the the list contains the terms that the target
+       could collect.
+       </entry><entry>none</entry></row>
+      <row><entry>
+        apdulog</entry><entry>
+       If set to a true value such as "1", a log of low-level
+        protocol packets is emitted on standard error stream.  This
+        can be very useful for debugging.
+       </entry><entry>0</entry></row>
+      <row><entry>
+        saveAPDU</entry><entry>
+       If set to a true value such as "1", a log of low-level
+        protocol packets is saved. The log can be retrieved by reading
+       option APDU. Setting saveAPDU always has the side effect of
+       resetting the currently saved log. This setting is
+       <emphasis>write-only</emphasis>. If read, NULL will be returned.
+       It is only recognized in
+       <function>ZOOM_connection_option_set</function>.
+       </entry><entry>0</entry></row>
+      <row><entry>
+        APDU</entry><entry>
+       Returns the log of protocol packets. Will be empty if logging
+       is not enabled (see saveAPDU above). This setting is
+       <emphasis>read-only</emphasis>. It is only recognized if used
+       in call to <function>ZOOM_connection_option_get</function> or
+       <function>ZOOM_connection_option_getl</function>.
+       </entry><entry></entry></row>

      </tbody>
     </tgroup>
    </table>
    <para>
     If either option <literal>lang</literal> or <literal>charset</literal>
      </tbody>
     </tgroup>
    </table>
    <para>
     If either option <literal>lang</literal> or <literal>charset</literal>

-    is set, then 
+    is set, then

     <ulink url="&url.z39.50.charneg;">
      Character Set and Language Negotiation</ulink> is in effect.
    </para>
    <synopsis>
     <ulink url="&url.z39.50.charneg;">
      Character Set and Language Negotiation</ulink> is in effect.
    </para>
    <synopsis>

-     int ZOOM_connection_error (ZOOM_connection c, const char **cp,
-                                const char **addinfo);
-     int ZOOM_connection_error_x (ZOOM_connection c, const char **cp,
-                                  const char **addinfo, const char **dset);
+     int ZOOM_connection_error(ZOOM_connection c, const char **cp,
+                               const char **addinfo);
+     int ZOOM_connection_error_x(ZOOM_connection c, const char **cp,
+                                 const char **addinfo, const char **dset);

    </synopsis>
    <para>
     Function <function>ZOOM_connection_error</function> checks for
    </synopsis>
    <para>
     Function <function>ZOOM_connection_error</function> checks for

@@ -341,14 +391,14 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
     </para>
     </sect2>
    <sect2 id="zoom.sru.init.behavior">
     </para>
     </sect2>
    <sect2 id="zoom.sru.init.behavior">

-    <title>SRU Protocol behavior</title>
+    <title>SRU/Solr Protocol behavior</title>

     <para>
     <para>

-     The SRU protocol doesn't feature an Inititialize Request, so
-     the connection phase merely establishes a TCP/IP connection
-     with the SOAP service.
+     The HTTP based protocols (SRU, SRW, Solr) doesn't feature an
+     Inititialize Request, so  the connection phase merely establishes a
+     TCP/IP connection with the HTTP server.

     </para>
     <para>Most of the ZOOM connection options do not
     </para>
     <para>Most of the ZOOM connection options do not

-     affect SRU and they are ignored. However, future versions
+     affect SRU/Solr 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.
      </para>
      of &yaz; might honor <literal>implementationName</literal> and
      put that as part of User-Agent header for HTTP requests.
      </para>

@@ -356,6 +406,19 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
      The <literal>charset</literal> is used in the Content-Type header
      of HTTP requests.
     </para>
      The <literal>charset</literal> is used in the Content-Type header
      of HTTP requests.
     </para>

+    <para>
+     Setting <literal>authentcationMode</literal> specifies how
+     authentication parameters are encoded for HTTP. The default is
+     "<literal>basic</literal>" where <literal>user</literal> and
+     <literal>password</literal> are encoded by using HTTP basic
+     authentication.
+     </para>
+    <para>
+     If <literal>authentcationMode</literal> is "<literal>url</literal>", then
+     user and password are encoded in the URL by parameters
+     <literal>x-username</literal> and <literal>x-password</literal> as
+     given by the SRU standard.
+    </para>

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

@@ -372,6 +435,9 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
      int ZOOM_query_cql(ZOOM_query s, const char *str);
 
      int ZOOM_query_sortby(ZOOM_query q, const char *criteria);
      int ZOOM_query_cql(ZOOM_query s, const char *str);
 
      int ZOOM_query_sortby(ZOOM_query q, const char *criteria);

+
+     int ZOOM_query_sortby2(ZOOM_query q, const char *strategy,
+                            const char *criteria);

    </synopsis>
    <para>
     Create query objects using <function>ZOOM_query_create</function>
    </synopsis>
    <para>
     Create query objects using <function>ZOOM_query_create</function>

@@ -384,17 +450,55 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
     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
     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 
-    sort criteria using the same string notation for sort as offered by
-    the <link linkend="sortspec">YAZ client</link>.
+    <function>ZOOM_query_sortby</function> enables Z39.50 sorting and
+    it takes sort criteria using the same string notation as
+    yaz-client's <link linkend="sortspec">sort command</link>.

    </para>
    </para>

-   <sect2 id="zoom.sort.behavior"><title>Protocol behavior</title>
-    <para>
-     The query object is just an interface for the member Query
-     in the SearchRequest. The sortby-function is an interface to the
-     sortSequence member of the SortRequest.
-    </para>
-   </sect2>
+   <para id="zoom.query.sortby2">
+    <function>ZOOM_query_sortby2</function> is similar to
+    <function>ZOOM_query_sortby</function> but allows a strategy for
+    sorting. The reason for the strategy parameter is that some
+    protocols offers multiple ways of performing sorting.
+    For example, Z39.50 has the standard sort, which is performed after
+    search on an existing result set.
+    It's also possible to use CQL in Z39.50 as the query type and use
+    CQL's SORTBY keyword. Finally, Index Data's
+    Zebra server also allows sorting to be specified as part of RPN (Type 7).
+   </para>
+   <table id="zoom-sort-strategy" frame="top">
+    <title>ZOOM sort strategy</title>
+    <tgroup cols="2">
+     <colspec colwidth="2*" colname="name"/>
+     <colspec colwidth="5*" colname="description"/>
+     <thead>
+      <row>
+       <entry>Name</entry>
+       <entry>Description</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>z39.50</entry><entry>Z39.50 resultset sort</entry>
+      </row>
+      <row>
+       <entry>type7</entry><entry>Sorting embedded in RPN(Type-7)</entry>
+      </row>
+      <row>
+       <entry>cql</entry><entry>CQL SORTBY</entry>
+      </row>
+      <row>
+       <entry>sru11</entry><entry>SRU sortKeys parameter</entry>
+      </row>
+      <row>
+       <entry>solr</entry><entry>Solr sort</entry>
+      </row>
+      <row>
+       <entry>embed</entry><entry>type7 for Z39.50, cql for SRU,
+       solr for Solr protocol</entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </table>

   </sect1>
   <sect1 id="zoom.resultsets"><title>Result sets</title>
    <para>
   </sect1>
   <sect1 id="zoom.resultsets"><title>Result sets</title>
    <para>

@@ -402,17 +506,15 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
     a target.
    </para>
    <synopsis>
     a target.
    </para>
    <synopsis>

-     ZOOM_resultset ZOOM_connection_search(ZOOM_connection,
-                                           ZOOM_query q);
+     ZOOM_resultset ZOOM_connection_search(ZOOM_connection, ZOOM_query q);

 
      ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c,
                                                const char *q);
 
      ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c,
                                                const char *q);

-

      void ZOOM_resultset_destroy(ZOOM_resultset r);
    </synopsis>
    <para>
     Function <function>ZOOM_connection_search</function> creates
      void ZOOM_resultset_destroy(ZOOM_resultset r);
    </synopsis>
    <para>
     Function <function>ZOOM_connection_search</function> creates

-     a result set given a connection and query.
+    a result set given a connection and query.

     Destroy a result set by calling
     <function>ZOOM_resultset_destroy</function>.
     Simple clients may using PQF only may use function
     Destroy a result set by calling
     <function>ZOOM_resultset_destroy</function>.
     Simple clients may using PQF only may use function

@@ -420,14 +522,12 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
     creating query objects is not necessary.
    </para>
    <synopsis>
     creating query objects is not necessary.
    </para>
    <synopsis>

-     void ZOOM_resultset_option_set (ZOOM_resultset r,
-                                      const char *key,
-                                      const char *val);
+     void ZOOM_resultset_option_set(ZOOM_resultset r,
+                                    const char *key, const char *val);

 
 

-     const char *ZOOM_resultset_option_get (ZOOM_resultset r,
-                                             const char *key);
+     const char *ZOOM_resultset_option_get(ZOOM_resultset r, const char *key);

 
 

-     size_t ZOOM_resultset_size (ZOOM_resultset r);
+     size_t ZOOM_resultset_size(ZOOM_resultset r);

    </synopsis>
    <para>
     Functions <function>ZOOM_resultset_options_set</function> and
    </synopsis>
    <para>
     Functions <function>ZOOM_resultset_options_set</function> and

@@ -439,7 +539,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
     The number of hits also called result-count is returned by
     function <function>ZOOM_resultset_size</function>.
    </para>
     The number of hits also called result-count is returned by
     function <function>ZOOM_resultset_size</function>.
    </para>

-   <table id="zoom.resultset.options" 
+   <table id="zoom.resultset.options"

     frame="top"><title>ZOOM Result set Options</title>
     <tgroup cols="3">
      <colspec colwidth="4*" colname="name"></colspec>
     frame="top"><title>ZOOM Result set Options</title>
     <tgroup cols="3">
      <colspec colwidth="4*" colname="name"></colspec>

@@ -454,22 +554,30 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
      </thead>
      <tbody>
       <row><entry>
      </thead>
      <tbody>
       <row><entry>

-        start</entry><entry>Offset of first record to be 
+        start</entry><entry>Offset of first record to be

         retrieved from target. First record has offset 0 unlike the
         protocol specifications where first record has position 1.
         retrieved from target. First record has offset 0 unlike the
         protocol specifications where first record has position 1.

+       This option affects ZOOM_resultset_search and
+       ZOOM_resultset_search_pqf and must be set before any of
+       these functions are invoked. If a range of
+       records must be fetched manually after search,
+       function ZOOM_resultset_records should be used.

        </entry><entry>0</entry></row>
       <row><entry>
         count</entry><entry>Number of records to be retrieved.
        </entry><entry>0</entry></row>
       <row><entry>
         count</entry><entry>Number of records to be retrieved.

+       This option affects ZOOM_resultset_search and
+       ZOOM_resultset_search_pqf and must be set before any of
+       these functions are invoked.

        </entry><entry>0</entry></row>
       <row><entry>
        presentChunk</entry><entry>The number of records to be
        </entry><entry>0</entry></row>
       <row><entry>
        presentChunk</entry><entry>The number of records to be

-       requested from the server in each chunk (present requst).  The
+       requested from the server in each chunk (present request). The

        value 0 means to request all the records in a single chunk.
        (The old <literal>step</literal>
        option is also supported for the benefit of old applications.)
        </entry><entry>0</entry></row>
       <row><entry>
        value 0 means to request all the records in a single chunk.
        (The old <literal>step</literal>
        option is also supported for the benefit of old applications.)
        </entry><entry>0</entry></row>
       <row><entry>

-        elementSetName</entry><entry>Element-Set name of records. 
+        elementSetName</entry><entry>Element-Set name of records.

         Most targets should honor element set name <literal>B</literal>
         and <literal>F</literal> for brief and full respectively.
        </entry><entry>none</entry></row>
         Most targets should honor element set name <literal>B</literal>
         and <literal>F</literal> for brief and full respectively.
        </entry><entry>none</entry></row>

@@ -504,14 +612,14 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
    </para>
    <para>
     This information is a list of of items, where each item is
    </para>
    <para>
     This information is a list of of items, where each item is

-    information about a term or subquery. All items in the list 
-    are prefixed by 
+    information about a term or subquery. All items in the list
+    are prefixed by

     <literal>SearchResult.</literal><replaceable>no</replaceable>
     <literal>SearchResult.</literal><replaceable>no</replaceable>

-    where no presents the item number (0=first, 1=second). 
+    where no presents the item number (0=first, 1=second).

     Read <literal>searchresult.size</literal> to determine the
     number of items.
    </para>
     Read <literal>searchresult.size</literal> to determine the
     number of items.
    </para>

-   <table id="zoom.search.info.report.options" 
+   <table id="zoom.search.info.report.options"

     frame="top"><title>Search Info Report Options</title>
     <tgroup cols="2">
      <colspec colwidth="4*" colname="name"></colspec>
     frame="top"><title>Search Info Report Options</title>
     <tgroup cols="2">
      <colspec colwidth="4*" colname="name"></colspec>

@@ -557,6 +665,31 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
      </tbody>
     </tgroup>
    </table>
      </tbody>
     </tgroup>
    </table>

+
+   <sect2 id="zoom.z3950.resultset.sort">
+    <title>Z39.50 Result-set Sort</title>
+    <synopsis>
+     void ZOOM_resultset_sort(ZOOM_resultset r,
+                              const char *sort_type, const char *sort_spec);
+
+     int ZOOM_resultset_sort1(ZOOM_resultset r,
+                              const char *sort_type, const char *sort_spec);
+    </synopsis>
+    <para>
+     <function>ZOOM_resultset_sort</function> and
+     <function>ZOOM_resultset_sort1</function> both sort an existing
+     result-set. The sort_type parameter is not use. Set it to "yaz".
+     The sort_spec is same notation as ZOOM_query_sortby and identical
+     to that offered by yaz-client's
+     <link linkend="sortspec">sort command</link>.
+    </para>
+    <para>
+     These functions only work for Z39.50. Use the more generic utility
+     <link linkend="zoom.query.sortby2">
+      <function>ZOOM_query_sortby2</function></link>
+     for other protocols (and even Z39.50).
+    </para>
+   </sect2>

    <sect2 id="zoom.z3950.resultset.behavior">
     <title>Z39.50 Protocol behavior</title>
     <para>
    <sect2 id="zoom.z3950.resultset.behavior">
     <title>Z39.50 Protocol behavior</title>
     <para>

@@ -624,13 +757,13 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
      <literal>preferredRecordSyntax</literal> are ignored.
     </para>
     <para>
      <literal>preferredRecordSyntax</literal> are ignored.
     </para>
     <para>

-     Options <literal>start</literal> and <literal>count</literal> 
+     Options <literal>start</literal> and <literal>count</literal>

      are supported by SRU.
      The remaining options
      are supported by SRU.
      The remaining options

-     <literal>piggyback</literal>, 
-     <literal>smallSetUpperBound</literal>, 
-     <literal>largeSetLowerBound</literal>, 
-     <literal>mediumSetPresentNumber</literal>, 
+     <literal>piggyback</literal>,
+     <literal>smallSetUpperBound</literal>,
+     <literal>largeSetLowerBound</literal>,
+     <literal>mediumSetPresentNumber</literal>,

      <literal>mediumSetElementSetName</literal>,
       <literal>smallSetElementSetName</literal> are
      unsupported.
      <literal>mediumSetElementSetName</literal>,
       <literal>smallSetElementSetName</literal> are
      unsupported.

@@ -642,9 +775,12 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
      SRU SearchRetrieveRequest.
     </para>
     <para>
      SRU SearchRetrieveRequest.
     </para>
     <para>

-     Unfortunately, SRU does not define a database setting. Hence,
+     Solr queries has to be done in Solr query format.
+    </para>
+    <para>
+     Unfortunately, SRU or Solr does not define a database setting. Hence,

      <literal>databaseName</literal> is unsupported and ignored.
      <literal>databaseName</literal> is unsupported and ignored.

-     However, the path part in host parameter for functions 
+     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; SRU server).
      <function>ZOOM_connecton_new</function> and
      <function>ZOOM_connection_connect</function> acts as a
      database (at least for the &yaz; SRU server).

@@ -668,12 +804,12 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
      int ZOOM_record_error(ZOOM_record rec, const char **msg,
                            const char **addinfo, const char **diagset);
 
      int ZOOM_record_error(ZOOM_record rec, const char **msg,
                            const char **addinfo, const char **diagset);
 

-     ZOOM_record ZOOM_record_clone (ZOOM_record rec);
+     ZOOM_record ZOOM_record_clone(ZOOM_record rec);

 
 

-     void ZOOM_record_destroy (ZOOM_record rec);
+     void ZOOM_record_destroy(ZOOM_record rec);

    </synopsis>
    <para>
    </synopsis>
    <para>

-    References to temporary records are returned by functions 
+    References to temporary records are returned by functions

     <function>ZOOM_resultset_records</function> or
     <function>ZOOM_resultset_record</function>.
     </para>
     <function>ZOOM_resultset_records</function> or
     <function>ZOOM_resultset_record</function>.
     </para>

@@ -685,7 +821,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
    </para>
    <para>
     A single record is returned by function
    </para>
    <para>
     A single record is returned by function

-    <function>ZOOM_resultset_record</function> that takes a 
+    <function>ZOOM_resultset_record</function> that takes a

     position as argument. First record has position zero.
     If no record could be obtained <literal>NULL</literal> is returned.
    </para>
     position as argument. First record has position zero.
     If no record could be obtained <literal>NULL</literal> is returned.
    </para>

@@ -718,22 +854,39 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
     The <parameter>type</parameter> is a string of the format:
    </para>
    <para>
     The <parameter>type</parameter> is a string of the format:
    </para>
    <para>

-    <replaceable>form</replaceable>[; charset=<replaceable>from</replaceable>[,<replaceable>to</replaceable>]]
+    <replaceable>format</replaceable>[;charset=<replaceable>from</replaceable>[/<replaceable>opacfrom</replaceable>][,<replaceable>to</replaceable>]][;format=<replaceable>v</replaceable>]

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

-    where <replaceable>form</replaceable> specifies the format of the
+    where <replaceable>format</replaceable> specifies the format of the

     returned record, <replaceable>from</replaceable>
     specifies the character set of the record in its original form
     (as returned by the server), <replaceable>to</replaceable> specifies
     the output (returned)
     character set encoding.
     returned record, <replaceable>from</replaceable>
     specifies the character set of the record in its original form
     (as returned by the server), <replaceable>to</replaceable> specifies
     the output (returned)
     character set encoding.

-    If charset is not given, then no character set conversion takes place.

     If <replaceable>to</replaceable> is omitted UTF-8 is assumed.
     If <replaceable>to</replaceable> is omitted UTF-8 is assumed.

+    If charset is not given, then no character set conversion takes place.
+   </para>
+
+   <para>OPAC records may be returned in a different
+     set from the bibliographic MARC record. If this is this the case,
+    <replaceable>opacfrom</replaceable> should be set to the character set
+    of the OPAC record part.
+   </para>
+   <note>
+     <para>
+       Specifying the OPAC record character set requires YAZ 4.1.5 or later.
+     </para>
+   </note>
+   <para>
+    The format argument controls whether record data should be XML
+    pretty-printed (post process operation).
+    It is enabled only if format value <replaceable>v</replaceable> is
+    <literal>1</literal> and the record content is XML well-formed.

    </para>
    <para>
     In addition, for certain types, the length
     <literal>len</literal> passed will be set to the size in bytes of
    </para>
    <para>
     In addition, for certain types, the length
     <literal>len</literal> passed will be set to the size in bytes of

-    the returned information. 
+    the returned information.

     </para>
    <para>
     The following are the supported values for <replaceable>form</replaceable>.
     </para>
    <para>
     The following are the supported values for <replaceable>form</replaceable>.

@@ -741,7 +894,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
      <varlistentry><term><literal>database</literal></term>
       <listitem><para>Database of record is returned
         as a C null-terminated string. Return type
      <varlistentry><term><literal>database</literal></term>
       <listitem><para>Database of record is returned
         as a C null-terminated string. Return type

-        <literal>const char *</literal>. 
+        <literal>const char *</literal>.

        </para></listitem>
      </varlistentry>
      <varlistentry><term><literal>syntax</literal></term>
        </para></listitem>
      </varlistentry>
      <varlistentry><term><literal>syntax</literal></term>

@@ -749,13 +902,13 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
         as a C null-terminated string containing the symbolic name of
        the record syntax, e.g. <literal>Usmarc</literal>. Return type
        is
         as a C null-terminated string containing the symbolic name of
        the record syntax, e.g. <literal>Usmarc</literal>. Return type
        is

-        <literal>const char *</literal>. 
+        <literal>const char *</literal>.

        </para></listitem>
      </varlistentry>
      <varlistentry><term><literal>schema</literal></term>
       <listitem><para>The schema of the record is returned
         as a C null-terminated string. Return type is
        </para></listitem>
      </varlistentry>
      <varlistentry><term><literal>schema</literal></term>
       <listitem><para>The schema of the record is returned
         as a C null-terminated string. Return type is

-        <literal>const char *</literal>. 
+        <literal>const char *</literal>.

        </para></listitem>
      </varlistentry>
      <varlistentry><term><literal>render</literal></term>
        </para></listitem>
      </varlistentry>
      <varlistentry><term><literal>render</literal></term>

@@ -768,7 +921,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
      <varlistentry><term><literal>raw</literal></term>
       <listitem><para>The record is returned in the internal
         YAZ specific format. For GRS-1, Explain, and others, the
      <varlistentry><term><literal>raw</literal></term>
       <listitem><para>The record is returned in the internal
         YAZ specific format. For GRS-1, Explain, and others, the

-        raw data is returned as type 
+        raw data is returned as type

         <literal>Z_External *</literal> which is just the type for
         the member <literal>retrievalRecord</literal> in
         type <literal>NamePlusRecord</literal>.
         <literal>Z_External *</literal> which is just the type for
         the member <literal>retrievalRecord</literal> in
         type <literal>NamePlusRecord</literal>.

@@ -778,28 +931,51 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
      </varlistentry>
      <varlistentry><term><literal>xml</literal></term>
       <listitem><para>The record is returned in XML if possible.
      </varlistentry>
      <varlistentry><term><literal>xml</literal></term>
       <listitem><para>The record is returned in XML if possible.

-       SRU and Z39.50 records with transfer syntax XML are
+       SRU, Solr and Z39.50 records with transfer syntax XML are

        returned verbatim. MARC records are returned in
        <ulink url="&url.marcxml;">
         MARCXML
        returned verbatim. MARC records are returned in
        <ulink url="&url.marcxml;">
         MARCXML

-        </ulink> 
+        </ulink>

        (converted from ISO2709 to MARCXML by YAZ).
        (converted from ISO2709 to MARCXML by YAZ).

-       GRS-1 and OPAC records are not supported for this form.
+       OPAC records are also converted to XML and the
+       bibliographic record is converted to MARCXML (when possible).
+       GRS-1 records are not supported for this form.

         Upon completion, the XML buffer is returned
        (type <literal>const char *</literal>) and length is stored in
         <literal>*len</literal>.
        </para></listitem>
      </varlistentry>
      <varlistentry><term><literal>opac</literal></term>
         Upon completion, the XML buffer is returned
        (type <literal>const char *</literal>) and length is stored in
         <literal>*len</literal>.
        </para></listitem>
      </varlistentry>
      <varlistentry><term><literal>opac</literal></term>

-      <listitem><para>OPAC for record is returned in XML.
+      <listitem><para>OPAC information for record is returned in XML
+       if an OPAC record is present at the position given. If no
+       OPAC record is present, a NULL pointer is returned.

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

+     <varlistentry><term><literal>txml</literal></term>
+      <listitem><para>The record is returned in TurboMARC if possible.
+       SRU and Z39.50 records with transfer syntax XML are
+       returned verbatim. MARC records are returned in
+       <link linkend="tools.turbomarc">
+        TurboMARC
+       </link>
+       (converted from ISO2709 to TurboMARC by YAZ).
+       Upon completion, the XML buffer is returned
+       (type <literal>const char *</literal>) and length is stored in
+        <literal>*len</literal>.
+       </para></listitem>
+     </varlistentry>
+     <varlistentry><term><literal>json</literal></term>
+      <listitem><para>Like xml, but MARC records are converted to
+       <ulink url="&url.marc_in_json;">MARC-in-JSON</ulink>.
+       </para></listitem>
+     </varlistentry>
+

     </variablelist>
    </para>
    <para>
     Most
     <ulink url="&url.marc21;">MARC21</ulink>
     </variablelist>
    </para>
    <para>
     Most
     <ulink url="&url.marc21;">MARC21</ulink>

-    records uses the 
+    records uses the

     <ulink url="&url.marc8;">MARC-8</ulink>
     character set encoding.
     An application that wishes to display in Latin-1 would use
     <ulink url="&url.marc8;">MARC-8</ulink>
     character set encoding.
     An application that wishes to display in Latin-1 would use

@@ -828,14 +1004,89 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
     </para>
    </sect2>
    <sect2 id="zoom.sru.record.behavior">
     </para>
    </sect2>
    <sect2 id="zoom.sru.record.behavior">

-    <title>SRU Protocol behavior</title>
+    <title>SRU/Solr Protocol behavior</title>

     <para>
     <para>

-     The ZOOM driver for SRU treats records returned by a SRU server
+     The ZOOM driver for SRU/Solr treats records returned by a SRU/Solr server

      as if they where Z39.50 records with transfer syntax XML and
      no element set name or database name.
     </para>
    </sect2>
   </sect1>
      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.facets"><title>Facets</title>
+   <para>
+    Facets operations is not part of the official ZOOM specification, but
+    is an Index Data extension for YAZ-based Z39.50 targets or
+    <ulink url="&url.solr;">Solr</ulink> targets.
+    In case the target can and is requested to return facets, using a
+    result set the ZOOM client can request one or all facet fields.
+    Using a facet field the client can request the term count and then
+    interate over the terms.
+   </para>
+   <synopsis>
+    ZOOM_facet_field *ZOOM_resultset_facets(ZOOM_resultset r);
+
+    const char ** ZOOM_resultset_facets_names(ZOOM_resultset r);
+
+    ZOOM_facet_field ZOOM_resultset_get_facet_field(ZOOM_resultset r,
+                                                    const char *facet_name);
+
+    ZOOM_facet_field ZOOM_resultset_get_facet_field_by_index(ZOOM_resultset r,
+                                                             int pos);
+
+    size_t ZOOM_resultset_facets_size(ZOOM_resultset r);
+
+    const char *ZOOM_facet_field_name(ZOOM_facet_field facet_field);
+
+    size_t ZOOM_facet_field_term_count(ZOOM_facet_field facet_field);
+
+    const char *ZOOM_facet_field_get_term(ZOOM_facet_field facet_field,
+                                          size_t idx, int *freq);
+   </synopsis>
+   <para>
+    References to temporary structures are returned by all functions.
+    They are only valid as long the Result set is valid.
+    <function>ZOOM_resultset_get_facet_field</function> or
+    <function>ZOOM_resultset_get_facet_field_by_index</function>.
+    <function>ZOOM_resultset_facets</function>.
+    <function>ZOOM_resultset_facets_names</function>.
+    <function>ZOOM_facet_field_name</function>.
+    <function>ZOOM_facet_field_get_term</function>.
+    </para>
+   <para id="zoom.resultset.get_facet_field">
+    A single Facet field  is returned by function
+    <function>ZOOM_resultset_get_facet_field</function> or
+    <function>ZOOM_resultset_get_facet_field_by_index</function> that takes
+    a  result set and facet name or positive index respectively. First
+    facet has position zero. If no facet could be obtained (invalid name
+    or index out of bounds) <literal>NULL</literal> is returned.
+   </para>
+   <para id="zoom.resultset.facets">
+    An array of facets field can be returned by
+    <function>ZOOM_resultset_facets</function>. The length of the array is
+    given by <function>ZOOM_resultset_facets_size</function>. The array is
+    zero-based and last entry will be at
+    <function>ZOOM_resultset_facets_size(result_set)</function>-1.
+   </para>
+   <para id="zoom.resultset.facets_names">
+    It is possible to interate over facets by name, by calling
+    <function>ZOOM_resultset_facets_names</function>.
+    This will return an const array of char * where each string can be used
+    as parameter for <function>ZOOM_resultset_get_facet_field</function>.
+   </para>
+   <para>
+   Function <function>ZOOM_facet_field_name</function> gets the request
+    facet name from a returned facet field.
+   </para>
+   <para>
+    Function <function>ZOOM_facet_field_get_term</function> returns the
+    idx'th term and term count for a facet field.
+    Idx must between 0 and
+    <function>ZOOM_facet_field_term_count</function>-1, otherwise the
+    returned reference will be <literal>NULL</literal>. On a valid idx, the
+    value of the freq reference will be the term count.
+    The <literal>freq</literal> parameter must be valid pointer to integer.
+   </para>
+   </sect1>

   <sect1 id="zoom.scan"><title>Scan</title>
    <para>
     This section describes an interface for Scan. Scan is not an
   <sect1 id="zoom.scan"><title>Scan</title>
    <para>
     This section describes an interface for Scan. Scan is not an

@@ -845,7 +1096,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
    </para>
 
    <para>
    </para>
 
    <para>

-    The Scan interface is supported for both Z39.50 and SRU.
+    The Scan interface is supported for both Z39.50, SRU and Solr.

    </para>
 
    <synopsis>
    </para>
 
    <synopsis>

@@ -857,16 +1108,16 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
 
     size_t ZOOM_scanset_size(ZOOM_scanset scan);
 
 
     size_t ZOOM_scanset_size(ZOOM_scanset scan);
 

-    const char * ZOOM_scanset_term(ZOOM_scanset scan, size_t pos,
-                                   int *occ, size_t *len);
+    const char *ZOOM_scanset_term(ZOOM_scanset scan, size_t pos,
+                                  size_t *occ, size_t *len);

 
 

-    const char * ZOOM_scanset_display_term(ZOOM_scanset scan, size_t pos,
-                                           int *occ, size_t *len);
+    const char *ZOOM_scanset_display_term(ZOOM_scanset scan, size_t pos,
+                                          size_t *occ, size_t *len);

 
 

-    void ZOOM_scanset_destroy (ZOOM_scanset scan);
+    void ZOOM_scanset_destroy(ZOOM_scanset scan);

 
     const char *ZOOM_scanset_option_get(ZOOM_scanset scan,
 
     const char *ZOOM_scanset_option_get(ZOOM_scanset scan,

-                                         const char *key);
+                                        const char *key);

 
     void ZOOM_scanset_option_set(ZOOM_scanset scan, const char *key,
                                  const char *val);
 
     void ZOOM_scanset_option_set(ZOOM_scanset scan, const char *key,
                                  const char *val);

@@ -884,7 +1135,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
     a scan set offset <literal>pos</literal> and returns a pointer
     to a <emphasis>raw term</emphasis> or <literal>NULL</literal> if
     non-present.
     a scan set offset <literal>pos</literal> and returns a pointer
     to a <emphasis>raw term</emphasis> or <literal>NULL</literal> if
     non-present.

-    If present, the <literal>occ</literal> and <literal>len</literal> 
+    If present, the <literal>occ</literal> and <literal>len</literal>

     are set to the number of occurrences and the length
     of the actual term respectively.
     <function>ZOOM_scanset_display_term</function> is similar to
     are set to the number of occurrences and the length
     of the actual term respectively.
     <function>ZOOM_scanset_display_term</function> is similar to

@@ -916,7 +1167,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
     more generic alternative to <function>ZOOM_connection_scan</function>
     which allows to use both CQL and PQF for Scan.
    </para>
     more generic alternative to <function>ZOOM_connection_scan</function>
     which allows to use both CQL and PQF for Scan.
    </para>

-   
+

    <table frame="top" id="zoom.scanset.options">
     <title>ZOOM Scan Set Options</title>
     <tgroup cols="3">
    <table frame="top" id="zoom.scanset.options">
     <title>ZOOM Scan Set Options</title>
     <tgroup cols="3">

@@ -934,7 +1185,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
       <row><entry>
         number</entry><entry>Number of Scan Terms requested in next scan.
         After scan it holds the actual number of terms returned.
       <row><entry>
         number</entry><entry>Number of Scan Terms requested in next scan.
         After scan it holds the actual number of terms returned.

-       </entry><entry>10</entry></row>
+       </entry><entry>20</entry></row>

       <row><entry>
         position</entry><entry>Preferred Position of term in response
         in next scan; actual position after completion of scan.
       <row><entry>
         position</entry><entry>Preferred Position of term in response
         in next scan; actual position after completion of scan.

@@ -1030,7 +1281,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
    </para>
    <para>
     <function>ZOOM_package_send</function> sends
    </para>
    <para>
     <function>ZOOM_package_send</function> sends

-    the package the via connection specified in 
+    the package the via connection specified in

     <function>ZOOM_connection_package</function>.
     The <parameter>type</parameter> specifies the actual extended service
     package type to be sent.
     <function>ZOOM_connection_package</function>.
     The <parameter>type</parameter> specifies the actual extended service
     package type to be sent.

@@ -1160,7 +1411,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
        <row>
        <entry>action</entry>
        <entry>
        <row>
        <entry>action</entry>
        <entry>

-        The update action. One of 
+        The update action. One of

         <literal>specialUpdate</literal>,
         <literal>recordInsert</literal>,
         <literal>recordReplace</literal>,
         <literal>specialUpdate</literal>,
         <literal>recordInsert</literal>,
         <literal>recordReplace</literal>,

@@ -1185,6 +1436,19 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
        <entry>none</entry>
        </row>
        <row>
        <entry>none</entry>
        </row>
        <row>

+       <entry>recordOpaque</entry>
+       <entry>Specifies an opaque record which is
+         encoded as an ASN.1 ANY type with the OID as tiven by option
+         <literal>syntax</literal> (see below).
+         Option <literal>recordOpaque</literal> is an alternative
+         to record - and <literal>record</literal> option (above) is
+         ignored if recordOpaque is set. This option is only available in
+         YAZ 3.0.35 and later and is meant to facilitate Updates with
+         servers from OCLC.
+       </entry>
+       <entry>none</entry>
+       </row>
+       <row>

        <entry>syntax</entry>
        <entry>The record syntax (transfer syntax). Is a string that
         is a known record syntax.
        <entry>syntax</entry>
        <entry>The record syntax (transfer syntax). Is a string that
         is a known record syntax.

@@ -1217,9 +1481,9 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
         1, 2 or 3. Each version has a distinct OID:
         1.2.840.10003.9.5
         (<ulink url="&url.z39.50.extupdate1;">first version</ulink>) ,
         1, 2 or 3. Each version has a distinct OID:
         1.2.840.10003.9.5
         (<ulink url="&url.z39.50.extupdate1;">first version</ulink>) ,

-        1.2.840.10003.9.5.1 
-        (second version) and 
-        1.2.840.10003.9.5.1.1 
+        1.2.840.10003.9.5.1
+        (second version) and
+        1.2.840.10003.9.5.1.1

         (<ulink url="&url.z39.50.extupdate3;">third and
          newest version</ulink>).
        </entry>
         (<ulink url="&url.z39.50.extupdate3;">third and
          newest version</ulink>).
        </entry>

@@ -1228,7 +1492,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
       </tbody>
      </tgroup>
     </table>
       </tbody>
      </tgroup>
     </table>

-    
+

    </sect2>
 
    <sect2 id="zoom.database.create"><title>Database Create</title>
    </sect2>
 
    <sect2 id="zoom.database.create"><title>Database Create</title>

@@ -1236,7 +1500,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
      For Database Create, type must be set to <literal>create</literal> in
      <function>ZOOM_package_send</function>.
     </para>
      For Database Create, type must be set to <literal>create</literal> in
      <function>ZOOM_package_send</function>.
     </para>

-    
+

     <table frame="top" id="zoom.database.create.options">
      <title>Database Create Options</title>
      <tgroup cols="3">
     <table frame="top" id="zoom.database.create.options">
      <title>Database Create Options</title>
      <tgroup cols="3">

@@ -1260,13 +1524,13 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
      </tgroup>
     </table>
    </sect2>
      </tgroup>
     </table>
    </sect2>

-   
+

    <sect2 id="zoom.database.drop"><title>Database Drop</title>
     <para>
      For Database Drop, type must be set to <literal>drop</literal> in
      <function>ZOOM_package_send</function>.
     </para>
    <sect2 id="zoom.database.drop"><title>Database Drop</title>
     <para>
      For Database Drop, type must be set to <literal>drop</literal> in
      <function>ZOOM_package_send</function>.
     </para>

-    
+

     <table frame="top" id="zoom.database.drop.options">
      <title>Database Drop Options</title>
      <tgroup cols="3">
     <table frame="top" id="zoom.database.drop.options">
      <title>Database Drop Options</title>
      <tgroup cols="3">

@@ -1290,7 +1554,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
      </tgroup>
     </table>
    </sect2>
      </tgroup>
     </table>
    </sect2>

-   
+

    <sect2 id="zoom.commit"><title>Commit Operation</title>
     <para>
      For Commit, type must be set to <literal>commit</literal> in
    <sect2 id="zoom.commit"><title>Commit Operation</title>
     <para>
      For Commit, type must be set to <literal>commit</literal> in

@@ -1321,35 +1585,67 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
     an associative array / hash.
    </para>
    <synopsis>
     an associative array / hash.
    </para>
    <synopsis>

-     ZOOM_options ZOOM_options_create (void);
+     ZOOM_options ZOOM_options_create(void);

 
 

-     ZOOM_options ZOOM_options_create_with_parent (ZOOM_options parent);
+     ZOOM_options ZOOM_options_create_with_parent(ZOOM_options parent);

 
 

-     void ZOOM_options_destroy (ZOOM_options opt);
+     void ZOOM_options_destroy(ZOOM_options opt);

    </synopsis>
    <synopsis>
    </synopsis>
    <synopsis>

-     const char *ZOOM_options_get (ZOOM_options opt, const char *name);
+     const char *ZOOM_options_get(ZOOM_options opt, const char *name);

 
 

-     void ZOOM_options_set (ZOOM_options opt, const char *name,
-                            const char *v);
+     void ZOOM_options_set(ZOOM_options opt, const char *name,
+                           const char *v);

    </synopsis>
    <synopsis>
      typedef const char *(*ZOOM_options_callback)
    </synopsis>
    <synopsis>
      typedef const char *(*ZOOM_options_callback)

-                                     (void *handle, const char *name);
+                            (void *handle, const char *name);

 
      ZOOM_options_callback
 
      ZOOM_options_callback

-             ZOOM_options_set_callback (ZOOM_options opt,
-                                        ZOOM_options_callback c,
-                                        void *handle);
+             ZOOM_options_set_callback(ZOOM_options opt,
+                                       ZOOM_options_callback c,
+                                       void *handle);
+   </synopsis>
+  </sect1>
+
+  <sect1 id="zoom.queryconversions"><title>Query conversions</title>
+   <synopsis>
+    int ZOOM_query_cql2rpn(ZOOM_query s, const char *cql_str,
+                           ZOOM_connection conn);
+
+    int ZOOM_query_ccl2rpn(ZOOM_query s, const char *ccl_str,
+                           const char *config,
+                           int *ccl_error, const char **error_string,
+                           int *error_pos);

    </synopsis>
    </synopsis>

+   <para>
+    <function>ZOOM_query_cql2rpn</function> translates the CQL string,
+    client-side, into RPN which may be passed to the server.
+    This is useful for server's that don't themselves
+    support CQL, for which <function>ZOOM_query_cql</function> is useless.
+    `conn' is used  only as a place to stash diagnostics if compilation
+    fails; if this information is not needed, a null pointer may be used.
+    The CQL conversion is driven by option <literal>cqlfile</literal> from
+    connection conn. This specifies a conversion file (eg pqf.properties)
+    which <emphasis>must</emphasis> be present.
+   </para>
+   <para>
+    <function>ZOOM_query_ccl2rpn</function> translates the CCL string,
+    client-side, into RPN which may be passed to the server.
+    The conversion is driven by the specification given by
+    <literal>config</literal>. Upon completion 0 is returned on success; -1
+    is returned on on failure. Om failure <literal>error_string</literal> and
+    <literal>error_pos</literal> holds error message and position of
+    first error in original CCL string.
+   </para>

   </sect1>
   <sect1 id="zoom.events"><title>Events</title>
    <para>
   </sect1>
   <sect1 id="zoom.events"><title>Events</title>
    <para>

-    If you're developing non-blocking applications, you have to deal 
+    If you're developing non-blocking applications, you have to deal

     with events.
    </para>
    <synopsis>
     with events.
    </para>
    <synopsis>

-    int ZOOM_event (int no, ZOOM_connection *cs);
+    int ZOOM_event(int no, ZOOM_connection *cs);

    </synopsis>
    <para>
     The <function>ZOOM_event</function> executes pending events for
    </synopsis>
    <para>
     The <function>ZOOM_event</function> executes pending events for

@@ -1435,7 +1731,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
    </table>
   </sect1>
  </chapter>
    </table>
   </sect1>
  </chapter>

- 
+

  <!-- Keep this comment at the end of the file
  Local variables:
  mode: sgml
  <!-- Keep this comment at the end of the file
  Local variables:
  mode: sgml

@@ -1450,4 +1746,4 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
  sgml-namecase-general:t
  End:
  -->
  sgml-namecase-general:t
  End:
  -->

- 
+