Reindent

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

diff --git a/doc/zoom.xml b/doc/zoom.xml
index 09be3d9..ac9eadb 100644 (file)
--- a/doc/zoom.xml
+++ b/doc/zoom.xml
@@ -17,10 +17,9 @@ 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_connection_scan1(ZOOM_connection c, ZOOM_query startterm)

 ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
 -->
 ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
 -->

-<!-- $Id: zoom.xml,v 1.46 2005-12-21 16:45:38 mike 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

@@ -32,9 +31,17 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
 
   <note>
    <para>
 
   <note>
    <para>

-    A recent addition to &yaz; is SRW support. You can now make
-    SRW ZOOM connections by specifying scheme <literal>http://</literal>
-    for the hostname for a connection.
+    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:
+    <literal>sru=get,http://sru.miketaylor.org.uk:80/sru.pl</literal>

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

@@ -49,7 +56,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
    There are other language bindings available for &yaz;, and still
    more
    are in active development. See the
    There are other language bindings available for &yaz;, and still
    more
    are in active development. See the

-   <ulink url="http://zoom.z3950.org/">ZOOM web-site</ulink> for
+   <ulink url="&url.zoom;">ZOOM web-site</ulink> for

    more information.
   </para>
   
    more information.
   </para>
   

@@ -75,7 +82,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
    protocol behavior, that describes how the API maps to the Z39.50
    protocol.
   </para>
    protocol behavior, that describes how the API maps to the Z39.50
    protocol.
   </para>

-  <sect1 id="zoom.connections"><title>Connections</title>
+  <sect1 id="zoom-connections"><title>Connections</title>

    
    <para>The Connection object is a session with a target.
    </para>
    
    <para>The Connection object is a session with a target.
    </para>

@@ -88,7 +95,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
     
     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

@@ -108,7 +115,7 @@ 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 SRW over HTTP.
+    The scheme <literal>http</literal> selects SRU over HTTP.

    </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

@@ -116,7 +123,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
     <literal><parameter>key</parameter>=<parameter>value</parameter></literal>
     sequences, each of which represents an option to be set into the
     connection structure <emphasis>before</emphasis> the
     <literal><parameter>key</parameter>=<parameter>value</parameter></literal>
     sequences, each of which represents an option to be set into the
     connection structure <emphasis>before</emphasis> the

-    protocol-level connection is forged and the initialisation
+    protocol-level connection is forged and the initialization

     handshake takes place.  This facility can be used to provide
     authentication credentials, as in host-strings such as:
     <literal>user=admin,password=halfAm4n,tcp:localhost:8017/db</literal>
     handshake takes place.  This facility can be used to provide
     authentication credentials, as in host-strings such as:
     <literal>user=admin,password=halfAm4n,tcp:localhost:8017/db</literal>

@@ -154,7 +161,8 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
     <function>ZOOM_connection_option_getl</function> returns
     the value for an option given by <parameter>key</parameter>.
    </para>
     <function>ZOOM_connection_option_getl</function> returns
     the value for an option given by <parameter>key</parameter>.
    </para>

-   <table frame="top"><title>ZOOM Connection Options</title>
+   <table id="zoom-connection-options" frame="top">
+    <title>ZOOM Connection Options</title>

     <tgroup cols="3">
      <colspec colwidth="4*" colname="name"></colspec>
      <colspec colwidth="7*" colname="description"></colspec>
     <tgroup cols="3">
      <colspec colwidth="4*" colname="name"></colspec>
      <colspec colwidth="7*" colname="description"></colspec>

@@ -252,20 +260,39 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
         mediumSetElementSetName</entry><entry>
         The element set name to be for medium-sized result sets.
        </entry><entry>none</entry></row>
         mediumSetElementSetName</entry><entry>
         The element set name to be for medium-sized result sets.
        </entry><entry>none</entry></row>

+      <row><entry>
+        init_opt_search, init_opt_present, init_opt_delSet, etc.</entry><entry>
+        After a successful Init, these options may be interrogated to
+       discover whether the server claims to support the specified
+       operations.
+       </entry><entry>none</entry></row>
+      <row><entry>
+        sru</entry><entry>
+       SRU transport type. Must be either <literal>soap</literal>,
+       <literal>get</literal> or <literal>post</literal>.
+       </entry><entry>soap</entry></row>
+      <row><entry>
+        sru_version</entry><entry>
+       SRU/SRW version. Should be <literal>1.1</literal>, or
+       <literal>1.2</literal>. This is , prior to connect, the 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.2</entry></row>

      </tbody>
     </tgroup>
    </table>
    <para>
     If either option <literal>lang</literal> or <literal>charset</literal>
     is set, then 
      </tbody>
     </tgroup>
    </table>
    <para>
     If either option <literal>lang</literal> or <literal>charset</literal>
     is set, then 

-    <ulink url="http://lcweb.loc.gov/z3950/agency/defns/charneg-3.html">
+    <ulink url="&url.z39.50.charneg;">

      Character Set and Language Negotiation</ulink> is in effect.
    </para>
    <synopsis>
      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

@@ -278,7 +305,8 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
     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>Z39.50 Protocol behavior</title>
+   <sect2 id="zoom-connection-z39.50">
+    <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

@@ -316,14 +344,15 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
      API cannot tell the outcome (yet).
     </para>
     </sect2>
      API cannot tell the outcome (yet).
     </para>
     </sect2>

-   <sect2><title>SRW Protocol behavior</title>
+   <sect2 id="zoom.sru.init.behavior">
+    <title>SRU Protocol behavior</title>

     <para>
     <para>

-     The SRW protocol doesn't feature an Inititialize Request, so
+     The SRU protocol doesn't feature an Inititialize Request, so

      the connection phase merely establishes a TCP/IP connection
      with the SOAP service.
     </para>
     <para>Most of the ZOOM connection options do not
      the connection phase merely establishes a TCP/IP connection
      with the SOAP service.
     </para>
     <para>Most of the ZOOM connection options do not

-     affect SRW and they are ignored. However, future versions
+     affect SRU 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>

@@ -363,7 +392,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
     sort criteria using the same string notation for sort as offered by
     the <link linkend="sortspec">YAZ client</link>.
    </para>
     sort criteria using the same string notation for sort as offered by
     the <link linkend="sortspec">YAZ client</link>.
    </para>

-   <sect2><title>Protocol behavior</title>
+   <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
     <para>
      The query object is just an interface for the member Query
      in the SearchRequest. The sortby-function is an interface to the

@@ -377,17 +406,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

@@ -395,14 +422,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

@@ -414,7 +439,8 @@ 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 frame="top"><title>ZOOM Result set Options</title>
+   <table id="zoom.resultset.options" 
+    frame="top"><title>ZOOM Result set Options</title>

     <tgroup cols="3">
      <colspec colwidth="4*" colname="name"></colspec>
      <colspec colwidth="7*" colname="description"></colspec>
     <tgroup cols="3">
      <colspec colwidth="4*" colname="name"></colspec>
      <colspec colwidth="7*" colname="description"></colspec>

@@ -431,13 +457,21 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
         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.
         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.

+       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>
        </entry><entry>0</entry></row>
       <row><entry>

-        count</entry><entry>Number of records to be retrieved.
+        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.)
        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.)

@@ -460,6 +494,13 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
         If this option isn't set, the ZOOM module will automatically
         allocate a result set name.
        </entry><entry>default</entry></row>
         If this option isn't set, the ZOOM module will automatically
         allocate a result set name.
        </entry><entry>default</entry></row>

+      <row><entry>
+        rpnCharset</entry><entry>Character set for RPN terms.
+        If this is set, ZOOM C will assume that the ZOOM application is
+        running UTF-8. Terms in RPN queries are then converted to the
+        rpnCharset. If this is unset, ZOOM C will not assume any encoding
+        of RPN terms and no conversion is performed.
+       </entry><entry>none</entry></row>

      </tbody>
     </tgroup>
    </table>
      </tbody>
     </tgroup>
    </table>

@@ -478,7 +519,8 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
     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 frame="top"><title>Search Info Report options</title>
+   <table id="zoom.search.info.report.options" 
+    frame="top"><title>Search Info Report Options</title>

     <tgroup cols="2">
      <colspec colwidth="4*" colname="name"></colspec>
      <colspec colwidth="7*" colname="description"></colspec>
     <tgroup cols="2">
      <colspec colwidth="4*" colname="name"></colspec>
      <colspec colwidth="7*" colname="description"></colspec>

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

-   <sect2>
+   <sect2 id="zoom.z3950.resultset.behavior">

     <title>Z39.50 Protocol behavior</title>
     <para>
      The creation of a result set involves at least a SearchRequest
     <title>Z39.50 Protocol behavior</title>
     <para>
      The creation of a result set involves at least a SearchRequest

@@ -575,23 +617,23 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
      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>
+   <sect2 id="zoom.sru.resultset.behavior">
+    <title>SRU Protocol behavior</title>

     <para>
      Current version of &yaz; does not take advantage of a result set id
     <para>
      Current version of &yaz; does not take advantage of a result set id

-     returned by the SRW server. Future versions might do, however.
+     returned by the SRU server. Future versions might do, however.

      Since, the ZOOM driver does not save result set IDs any
      Since, the ZOOM driver does not save result set IDs any

-     present (retrieval) is transformed to a SRW SearchRetrieveRequest
+     present (retrieval) is transformed to a SRU SearchRetrieveRequest

      with same query but, possibly, different offsets.
     </para>
     <para>
      with same query but, possibly, different offsets.
     </para>
     <para>

-     Option <literal>schema</literal> specifies SRW schema
+     Option <literal>schema</literal> specifies SRU schema

      for retrieval. However, options <literal>elementSetName</literal> and
      <literal>preferredRecordSyntax</literal> are ignored.
     </para>
     <para>
      Options <literal>start</literal> and <literal>count</literal> 
      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.
+     are supported by SRU.

      The remaining options
      <literal>piggyback</literal>, 
      <literal>smallSetUpperBound</literal>, 
      The remaining options
      <literal>piggyback</literal>, 
      <literal>smallSetUpperBound</literal>, 

@@ -602,18 +644,18 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
      unsupported.
     </para>
     <para>
      unsupported.
     </para>
     <para>

-     SRW supports CQL queries, <emphasis>not</emphasis> PQF.
+     SRU 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
      If PQF is used, however, the PQF query is transferred anyway
      using non-standard element <literal>pQuery</literal> in

-     SRW SearchRetrieveRequest.
+     SRU SearchRetrieveRequest.

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

-     Unfortunately, SRW does not define a database setting. Hence,
+     Unfortunately, SRU 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
      <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).
+     database (at least for the &yaz; SRU server).

     </para>
    </sect2>
   </sect1>
     </para>
    </sect2>
   </sect1>

@@ -623,17 +665,20 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
     created from result sets.
    </para>
    <synopsis>
     created from result sets.
    </para>
    <synopsis>

-     void ZOOM_resultset_records (ZOOM_resultset r,
-                                  ZOOM_record *recs,
-                                  size_t start, size_t count);
-     ZOOM_record ZOOM_resultset_record (ZOOM_resultset s, size_t pos);
+     void ZOOM_resultset_records(ZOOM_resultset r,
+                                 ZOOM_record *recs,
+                                 size_t start, size_t count);
+     ZOOM_record ZOOM_resultset_record(ZOOM_resultset s, size_t pos);

 
 

-     const char *ZOOM_record_get (ZOOM_record rec, const char *type,
-                                  size_t *len);
+     const char *ZOOM_record_get(ZOOM_record rec, const char *type,
+                                 size_t *len);

 
 

-     ZOOM_record ZOOM_record_clone (ZOOM_record rec);
+     int ZOOM_record_error(ZOOM_record rec, const char **msg,
+                           const char **addinfo, const char **diagset);

 
 

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

    </synopsis>
    <para>
     References to temporary records are returned by functions 
    </synopsis>
    <para>
     References to temporary records are returned by functions 

@@ -653,6 +698,12 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
     If no record could be obtained <literal>NULL</literal> is returned.
    </para>
    <para>
     If no record could be obtained <literal>NULL</literal> is returned.
    </para>
    <para>

+    Error information for a record can be checked with
+    <function>ZOOM_record_error</function> which returns non-zero
+    (error code) if record is in error, called <emphasis>Surrogate
+     Diagnostics</emphasis> in Z39.50.
+   </para>
+   <para>

     Function <function>ZOOM_resultset_records</function> retrieves
     a number of records from a result set. Parameter <literal>start</literal>
     and <literal>count</literal> specifies the range of records to
     Function <function>ZOOM_resultset_records</function> retrieves
     a number of records from a result set. Parameter <literal>start</literal>
     and <literal>count</literal> specifies the range of records to

@@ -709,6 +760,12 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
         <literal>const char *</literal>. 
        </para></listitem>
      </varlistentry>
         <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
+        <literal>const char *</literal>. 
+       </para></listitem>
+     </varlistentry>

      <varlistentry><term><literal>render</literal></term>
       <listitem><para>The record is returned in a display friendly
         format. Upon completion buffer is returned
      <varlistentry><term><literal>render</literal></term>
       <listitem><para>The record is returned in a display friendly
         format. Upon completion buffer is returned

@@ -729,9 +786,9 @@ 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.

-       SRW/SRU and Z39.50 records with transfer syntax XML are
+       SRU and Z39.50 records with transfer syntax XML are

        returned verbatim. MARC records are returned in
        returned verbatim. MARC records are returned in

-       <ulink url="http://www.loc.gov/standards/marcxml/">
+       <ulink url="&url.marcxml;">

         MARCXML
         </ulink> 
        (converted from ISO2709 to MARCXML by YAZ).
         MARCXML
         </ulink> 
        (converted from ISO2709 to MARCXML by YAZ).

@@ -749,20 +806,17 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
    </para>
    <para>
     Most
    </para>
    <para>
     Most

-    <ulink url="http://www.loc.gov/marc/">
-     MARC21
-    </ulink>
+    <ulink url="&url.marc21;">MARC21</ulink>

     records uses the 
     records uses the 

-    <ulink url="http://www.loc.gov/marc/specifications/speccharmarc8.html">
-     MARC-8
-    </ulink>
+    <ulink url="&url.marc8;">MARC-8</ulink>

     character set encoding.
     An application that wishes to display in Latin-1 would use
     <screen>
      render; charset=marc8,iso-8859-1
     </screen>
    </para>
     character set encoding.
     An application that wishes to display in Latin-1 would use
     <screen>
      render; charset=marc8,iso-8859-1
     </screen>
    </para>

-   <sect2><title>Z39.50 Protocol behavior</title>
+   <sect2 id="zoom.z3950.record.behavior">
+    <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

@@ -781,9 +835,10 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
      <emphasis>now</emphasis>.
     </para>
    </sect2>
      <emphasis>now</emphasis>.
     </para>
    </sect2>

-   <sect2><title>SRW Protocol behavior</title>
+   <sect2 id="zoom.sru.record.behavior">
+    <title>SRU Protocol behavior</title>

     <para>
     <para>

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

      as if they where Z39.50 records with transfer syntax XML and
      no element set name or database name.
     </para>
      as if they where Z39.50 records with transfer syntax XML and
      no element set name or database name.
     </para>

@@ -798,14 +853,16 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
    </para>
 
    <para>
    </para>
 
    <para>

-    The Scan interface is Z39.50 only. SRW version 1.0 does not
-    support this.
+    The Scan interface is supported for both Z39.50 and SRU.

    </para>
 
    <synopsis>
     ZOOM_scanset ZOOM_connection_scan(ZOOM_connection c,
                                       const char *startpqf);
 
    </para>
 
    <synopsis>
     ZOOM_scanset ZOOM_connection_scan(ZOOM_connection c,
                                       const char *startpqf);
 

+    ZOOM_scanset ZOOM_connection_scan1(ZOOM_connection c,
+                                       ZOOM_query q);
+

     size_t ZOOM_scanset_size(ZOOM_scanset scan);
 
     const char * ZOOM_scanset_term(ZOOM_scanset scan, size_t pos,
     size_t ZOOM_scanset_size(ZOOM_scanset scan);
 
     const char * ZOOM_scanset_term(ZOOM_scanset scan, size_t pos,

@@ -814,10 +871,10 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
     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,
                                            int *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);

@@ -861,8 +918,15 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
      @attr 1=4 @attr 6=2 "science o"
     </literallayout>
    </para>
      @attr 1=4 @attr 6=2 "science o"
     </literallayout>
    </para>

+
+   <para>
+    The <function>ZOOM_connecton_scan1</function> is a newer and
+    more generic alternative to <function>ZOOM_connection_scan</function>
+    which allows to use both CQL and PQF for Scan.
+   </para>

    
    

-   <table frame="top"><title>ZOOM Scan Set Options</title>
+   <table frame="top" id="zoom.scanset.options">
+    <title>ZOOM Scan Set Options</title>

     <tgroup cols="3">
      <colspec colwidth="4*" colname="name"></colspec>
      <colspec colwidth="7*" colname="description"></colspec>
     <tgroup cols="3">
      <colspec colwidth="4*" colname="name"></colspec>
      <colspec colwidth="7*" colname="description"></colspec>

@@ -890,12 +954,19 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
         scanStatus</entry><entry>An integer indicating the Scan Status
         of last scan.
        </entry><entry>0</entry></row>
         scanStatus</entry><entry>An integer indicating the Scan Status
         of last scan.
        </entry><entry>0</entry></row>

+      <row><entry>
+        rpnCharset</entry><entry>Character set for RPN terms.
+        If this is set, ZOOM C will assume that the ZOOM application is
+        running UTF-8. Terms in RPN queries are then converted to the
+        rpnCharset. If this is unset, ZOOM C will not assume any encoding
+        of RPN terms and no conversion is performed.
+       </entry><entry>none</entry></row>

      </tbody>
     </tgroup>
    </table>
   </sect1>
 
      </tbody>
     </tgroup>
    </table>
   </sect1>
 

-  <sect1 id="zoom.ext"><title>Extended Services</title>
+  <sect1 id="zoom.extendedservices"><title>Extended Services</title>

    <para>
     ZOOM offers an interface to a subset of the Z39.50 extended services
     as well as a few privately defined ones:
    <para>
     ZOOM offers an interface to a subset of the Z39.50 extended services
     as well as a few privately defined ones:

@@ -904,35 +975,35 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
     <listitem>
      <para>
       Z39.50 Item Order (ILL).
     <listitem>
      <para>
       Z39.50 Item Order (ILL).

-      See <xref linkend="zoom.ext.itemorder"/>.
+      See <xref linkend="zoom.item.order"/>.

      </para>
     </listitem>
     <listitem>
      <para>
       Record Update. This allows a client to insert, modify or delete
       records.
      </para>
     </listitem>
     <listitem>
      <para>
       Record Update. This allows a client to insert, modify or delete
       records.

-      See <xref linkend="zoom.ext.update"/>.
+      See <xref linkend="zoom.record.update"/>.

      </para>
     </listitem>
     <listitem>
      <para>
       Database Create. This a non-standard feature. Allows a client
       to create a database.
      </para>
     </listitem>
     <listitem>
      <para>
       Database Create. This a non-standard feature. Allows a client
       to create a database.

-      See <xref linkend="zoom.ext.dbcreate"/>.
+      See <xref linkend="zoom.database.create"/>.

      </para>
     </listitem>
     <listitem>
      <para>
       Database Drop. This a non-standard feature. Allows a client
       to delete/drop a database.
      </para>
     </listitem>
     <listitem>
      <para>
       Database Drop. This a non-standard feature. Allows a client
       to delete/drop a database.

-      See <xref linkend="zoom.ext.dbdrop"/>.
+      See <xref linkend="zoom.database.drop"/>.

      </para>
      </listitem>
     <listitem>
      <para>
       Commit operation. This a non-standard feature. Allows a client
       to commit operations.
      </para>
      </listitem>
     <listitem>
      <para>
       Commit operation. This a non-standard feature. Allows a client
       to commit operations.

-      See <xref linkend="zoom.ext.commit"/>.
+      See <xref linkend="zoom.commit"/>.

      </para>
     </listitem>
     <!-- all the ILL PDU options should go here too -->
      </para>
     </listitem>
     <!-- all the ILL PDU options should go here too -->

@@ -973,7 +1044,8 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
     package type to be sent.
    </para>
 
     package type to be sent.
    </para>
 

-   <table frame="top"><title>Extended Service Common Options</title>
+   <table frame="top" id="zoom.extendedservices.options">
+    <title>Extended Service Common Options</title>

     <tgroup cols="3">
      <colspec colwidth="4*" colname="name"></colspec>
      <colspec colwidth="7*" colname="description"></colspec>
     <tgroup cols="3">
      <colspec colwidth="4*" colname="name"></colspec>
      <colspec colwidth="7*" colname="description"></colspec>

@@ -1007,10 +1079,19 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
        <entry><literal>create</literal></entry>
       </row>
       <row>
        <entry><literal>create</literal></entry>
       </row>
       <row>

+       <entry>waitAction</entry>
+       <entry>
+       Wait action for package. Possible values:
+       <literal>wait</literal>, <literal>waitIfPossible</literal>,
+       <literal>dontWait</literal> or <literal>dontReturnPackage</literal>.
+       </entry>
+       <entry><literal>waitIfPossible</literal></entry>
+      </row>
+      <row>

        <entry>targetReference</entry>
        <entry>
        Target Reference. This is part of the response as returned
        <entry>targetReference</entry>
        <entry>
        Target Reference. This is part of the response as returned

-       by the server. Read it after a succesful operation.
+       by the server. Read it after a successful operation.

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

@@ -1018,13 +1099,14 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
     </tgroup>
    </table>
 
     </tgroup>
    </table>
 

-   <sect2 id="zoom.ext.itemorder"><title>Item Order</title>
+   <sect2 id="zoom.item.order"><title>Item Order</title>

     <para>
      For Item Order, type must be set to <literal>itemorder</literal> in
      <function>ZOOM_package_send</function>.
     </para>
 
     <para>
      For Item Order, type must be set to <literal>itemorder</literal> in
      <function>ZOOM_package_send</function>.
     </para>
 

-    <table frame="top"><title>Item Order Options</title>
+    <table frame="top" id="zoom.item.order.options">
+     <title>Item Order Options</title>

      <tgroup cols="3">
       <colspec colwidth="4*" colname="name"></colspec>
       <colspec colwidth="7*" colname="description"></colspec>
      <tgroup cols="3">
       <colspec colwidth="4*" colname="name"></colspec>
       <colspec colwidth="7*" colname="description"></colspec>

@@ -1063,13 +1145,14 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
 
    </sect2>
 
 
    </sect2>
 

-   <sect2 id="zoom.ext.update"><title>Record Update</title>
+   <sect2 id="zoom.record.update"><title>Record Update</title>

     <para>
      For Record Update, type must be set to <literal>update</literal> in
      <function>ZOOM_package_send</function>.
     </para>
 
     <para>
      For Record Update, type must be set to <literal>update</literal> in
      <function>ZOOM_package_send</function>.
     </para>
 

-    <table frame="top"><title>Record Update Options</title>
+    <table frame="top" id="zoom.record.update.options">
+     <title>Record Update Options</title>

      <tgroup cols="3">
       <colspec colwidth="4*" colname="name"></colspec>
       <colspec colwidth="7*" colname="description"></colspec>
      <tgroup cols="3">
       <colspec colwidth="4*" colname="name"></colspec>
       <colspec colwidth="7*" colname="description"></colspec>

@@ -1092,7 +1175,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
         <literal>recordDelete</literal>,
         <literal>elementUpdate</literal>.
        </entry>
         <literal>recordDelete</literal>,
         <literal>elementUpdate</literal>.
        </entry>

-       <entry><literal>specialUpdate</literal></entry>
+       <entry><literal>specialUpdate (recordInsert for updateVersion=1 which does not support specialUpdate)</literal></entry>

        </row>
        <row>
        <entry>recordIdOpaque</entry>
        </row>
        <row>
        <entry>recordIdOpaque</entry>

@@ -1110,6 +1193,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.

@@ -1121,19 +1217,49 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
        <entry>Database from connection object</entry>
        <entry>Default</entry>
        </row>
        <entry>Database from connection object</entry>
        <entry>Default</entry>
        </row>

+       <row>
+       <entry>correlationInfo.note</entry>
+       <entry>Correlation Info Note (string)</entry>
+       <entry>none</entry>
+       </row>
+       <row>
+       <entry>correlationInfo.id</entry>
+       <entry>Correlation Info ID (integer)</entry>
+       <entry>none</entry>
+       </row>
+       <row>
+       <entry>elementSetName</entry>
+       <entry>Element Set for Record</entry>
+       <entry>none</entry>
+       </row>
+       <row>
+       <entry>updateVersion</entry>
+       <entry>Record Update version which holds one of the values
+        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 
+        (<ulink url="&url.z39.50.extupdate3;">third and
+         newest version</ulink>).
+       </entry>
+       <entry>3</entry>
+       </row>

       </tbody>
      </tgroup>
     </table>
     
    </sect2>
 
       </tbody>
      </tgroup>
     </table>
     
    </sect2>
 

-   <sect2 id="zoom.ext.dbcreate"><title>Database Create</title>
+   <sect2 id="zoom.database.create"><title>Database Create</title>

     <para>
      For Database Create, type must be set to <literal>create</literal> in
      <function>ZOOM_package_send</function>.
     </para>
     
     <para>
      For Database Create, type must be set to <literal>create</literal> in
      <function>ZOOM_package_send</function>.
     </para>
     

-    <table frame="top"><title>Database Create Options</title>
+    <table frame="top" id="zoom.database.create.options">
+     <title>Database Create Options</title>

      <tgroup cols="3">
       <colspec colwidth="4*" colname="name"></colspec>
       <colspec colwidth="7*" colname="description"></colspec>
      <tgroup cols="3">
       <colspec colwidth="4*" colname="name"></colspec>
       <colspec colwidth="7*" colname="description"></colspec>

@@ -1156,13 +1282,14 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
     </table>
    </sect2>
    
     </table>
    </sect2>
    

-   <sect2 id="zoom.ext.dbdrop"><title>Database Drop</title>
+   <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>
     
     <para>
      For Database Drop, type must be set to <literal>drop</literal> in
      <function>ZOOM_package_send</function>.
     </para>
     

-    <table frame="top"><title>Database Create Options</title>
+    <table frame="top" id="zoom.database.drop.options">
+     <title>Database Drop Options</title>

      <tgroup cols="3">
       <colspec colwidth="4*" colname="name"></colspec>
       <colspec colwidth="7*" colname="description"></colspec>
      <tgroup cols="3">
       <colspec colwidth="4*" colname="name"></colspec>
       <colspec colwidth="7*" colname="description"></colspec>

@@ -1185,14 +1312,15 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
     </table>
    </sect2>
    
     </table>
    </sect2>
    

-   <sect2 id="zoom.ext.commit"><title>Commit Operation</title>
+   <sect2 id="zoom.commit"><title>Commit Operation</title>

     <para>
      For Commit, type must be set to <literal>commit</literal> in
      <function>ZOOM_package_send</function>.
     </para>
    </sect2>
 
     <para>
      For Commit, type must be set to <literal>commit</literal> in
      <function>ZOOM_package_send</function>.
     </para>
    </sect2>
 

-   <sect2><title>Protocol behavior</title>
+   <sect2 id="zoom.extended.services.behavior">
+    <title>Protocol behavior</title>

     <para>
      All the extended services are Z39.50-only.
     </para>
     <para>
      All the extended services are Z39.50-only.
     </para>

@@ -1214,26 +1342,26 @@ 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.events"><title>Events</title>
    </synopsis>
   </sect1>
   <sect1 id="zoom.events"><title>Events</title>

@@ -1242,7 +1370,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
     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

@@ -1271,7 +1399,8 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
     (integer) for the last event.
    </para>
 
     (integer) for the last event.
    </para>
 

-   <table frame="top"><title>ZOOM Event IDs</title>
+   <table frame="top" id="zoom.event.ids">
+    <title>ZOOM Event IDs</title>

     <tgroup cols="2">
      <colspec colwidth="4*" colname="name"></colspec>
      <colspec colwidth="7*" colname="description"></colspec>
     <tgroup cols="2">
      <colspec colwidth="4*" colname="name"></colspec>
      <colspec colwidth="7*" colname="description"></colspec>