Update headers and omit CVS Ids.

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

diff --git a/doc/zoom.xml b/doc/zoom.xml
index 5ca4272..5d89f45 100644 (file)
--- a/doc/zoom.xml
+++ b/doc/zoom.xml
@@ -17,8 +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_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)

 -->
 -->

-<!-- $Id: zoom.xml,v 1.44 2005-11-16 16:04:19 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

@@ -30,9 +31,17 @@ ZOOM_options_set_int(opt, name, value)
 
   <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>
 

@@ -47,7 +56,7 @@ ZOOM_options_set_int(opt, name, value)
    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>
   

@@ -73,7 +82,7 @@ ZOOM_options_set_int(opt, name, value)
    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>

@@ -106,7 +115,18 @@ ZOOM_options_set_int(opt, name, value)
    <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
+    comma-separated
+    <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 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>

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

@@ -141,7 +161,8 @@ ZOOM_options_set_int(opt, name, value)
     <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>

@@ -239,13 +260,27 @@ ZOOM_options_set_int(opt, name, value)
         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_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>

@@ -265,7 +300,8 @@ ZOOM_options_set_int(opt, name, value)
     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

@@ -303,14 +339,15 @@ ZOOM_options_set_int(opt, name, value)
      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>

@@ -350,7 +387,7 @@ ZOOM_options_set_int(opt, name, value)
     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

@@ -401,7 +438,8 @@ ZOOM_options_set_int(opt, name, value)
     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>

@@ -447,6 +485,13 @@ ZOOM_options_set_int(opt, name, value)
         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>

@@ -465,7 +510,8 @@ ZOOM_options_set_int(opt, name, value)
     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>

@@ -510,7 +556,7 @@ ZOOM_options_set_int(opt, name, value)
      </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

@@ -562,23 +608,23 @@ ZOOM_options_set_int(opt, name, value)
      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>, 

@@ -589,18 +635,18 @@ ZOOM_options_set_int(opt, name, value)
      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>

@@ -610,13 +656,16 @@ ZOOM_options_set_int(opt, name, value)
     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);
+
+     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);
 

@@ -640,6 +689,12 @@ ZOOM_options_set_int(opt, name, value)
     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

@@ -696,6 +751,12 @@ ZOOM_options_set_int(opt, name, value)
         <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

@@ -716,9 +777,9 @@ ZOOM_options_set_int(opt, name, value)
      </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).

@@ -736,20 +797,17 @@ ZOOM_options_set_int(opt, name, value)
    </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

@@ -768,9 +826,10 @@ ZOOM_options_set_int(opt, name, value)
      <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>

@@ -785,14 +844,16 @@ ZOOM_options_set_int(opt, name, value)
    </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,

@@ -848,8 +909,15 @@ ZOOM_options_set_int(opt, name, value)
      @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>

@@ -877,12 +945,19 @@ ZOOM_options_set_int(opt, name, value)
         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:

@@ -891,35 +966,35 @@ ZOOM_options_set_int(opt, name, value)
     <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 -->

@@ -960,7 +1035,8 @@ ZOOM_options_set_int(opt, name, value)
     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>

@@ -994,10 +1070,19 @@ ZOOM_options_set_int(opt, name, value)
        <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>

@@ -1005,13 +1090,14 @@ ZOOM_options_set_int(opt, name, value)
     </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>

@@ -1050,13 +1136,14 @@ ZOOM_options_set_int(opt, name, value)
 
    </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>

@@ -1079,7 +1166,7 @@ ZOOM_options_set_int(opt, name, value)
         <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>

@@ -1108,19 +1195,49 @@ ZOOM_options_set_int(opt, name, value)
        <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>

@@ -1143,13 +1260,14 @@ ZOOM_options_set_int(opt, name, value)
     </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>

@@ -1172,14 +1290,15 @@ ZOOM_options_set_int(opt, name, value)
     </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>

@@ -1258,7 +1377,8 @@ ZOOM_options_set_int(opt, name, value)
     (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>