X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fzoom.xml;h=0d0bac22e8eed7f713924c01375a8159adb74f37;hb=b7e0b586c47f8cc0c99f0195e0b554dc5f1af072;hp=5ca427241c7b049d9f92c7950f2d598b45b4b2f2;hpb=4102d95bf434baaf92b1a8db63d1f7396c8e469f;p=yaz-moved-to-github.git

diff --git a/doc/zoom.xml b/doc/zoom.xml
index 5ca4272..0d0bac2 100644
--- a/doc/zoom.xml
+++ b/doc/zoom.xml
@@ -17,8 +17,10 @@ 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_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 $ -->
+<!-- $Id: zoom.xml,v 1.55 2006-12-06 11:12:14 mike Exp $ -->
  <chapter id="zoom"><title>ZOOM</title>
   <para>
     &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is
@@ -30,9 +32,13 @@ ZOOM_options_set_int(opt, name, value)
 
   <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>).
    </para>
   </note>
 
@@ -47,7 +53,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
-   <ulink url="http://zoom.z3950.org/">ZOOM web-site</ulink> for
+   <ulink url="&url.zoom;">ZOOM web-site</ulink> for
    more information.
   </para>
   
@@ -73,7 +79,7 @@ ZOOM_options_set_int(opt, name, value)
    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>
@@ -106,7 +112,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).
-    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 initialisation
+    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
@@ -141,7 +158,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>
-   <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>
@@ -239,13 +257,19 @@ 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>
+      <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>
      </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>
@@ -265,7 +289,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>
-   <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
@@ -303,14 +328,15 @@ ZOOM_options_set_int(opt, name, value)
      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>
-     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
-     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>
@@ -350,7 +376,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>
-   <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
@@ -401,7 +427,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>
-   <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>
@@ -465,7 +492,8 @@ ZOOM_options_set_int(opt, name, value)
     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>
@@ -510,7 +538,7 @@ ZOOM_options_set_int(opt, name, value)
      </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
@@ -562,23 +590,23 @@ ZOOM_options_set_int(opt, name, value)
      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
-     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
-     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>
-     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> 
-     are supported by SRW.
+     are supported by SRU.
      The remaining options
      <literal>piggyback</literal>, 
      <literal>smallSetUpperBound</literal>, 
@@ -589,18 +617,18 @@ ZOOM_options_set_int(opt, name, value)
      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
-     SRW SearchRetrieveRequest.
+     SRU SearchRetrieveRequest.
     </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
-     database (at least for the &yaz; SRW server).
+     database (at least for the &yaz; SRU server).
     </para>
    </sect2>
   </sect1>
@@ -610,13 +638,16 @@ ZOOM_options_set_int(opt, name, value)
     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);
 
@@ -640,6 +671,12 @@ ZOOM_options_set_int(opt, name, value)
     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
@@ -716,9 +753,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.
-	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
-	<ulink url="http://www.loc.gov/standards/marcxml/">
+	<ulink url="&url.marcxml;">
 	 MARCXML
 	 </ulink> 
 	(converted from ISO2709 to MARCXML by YAZ).
@@ -736,20 +773,17 @@ ZOOM_options_set_int(opt, name, value)
    </para>
    <para>
     Most
-    <ulink url="http://www.loc.gov/marc/">
-     MARC21
-    </ulink>
+    <ulink url="&url.marc21;">MARC21</ulink>
     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>
-   <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
@@ -768,9 +802,10 @@ ZOOM_options_set_int(opt, name, value)
      <emphasis>now</emphasis>.
     </para>
    </sect2>
-   <sect2><title>SRW Protocol behavior</title>
+   <sect2 id="zoom.sru.record.behavior">
+    <title>SRU Protocol behavior</title>
     <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>
@@ -849,7 +884,8 @@ ZOOM_options_set_int(opt, name, value)
     </literallayout>
    </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>
@@ -882,7 +918,7 @@ ZOOM_options_set_int(opt, name, value)
    </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:
@@ -891,35 +927,35 @@ ZOOM_options_set_int(opt, name, value)
     <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.
-      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.
-      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.
-      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.
-      See <xref linkend="zoom.ext.commit"/>.
+      See <xref linkend="zoom.commit"/>.
      </para>
     </listitem>
     <!-- all the ILL PDU options should go here too -->
@@ -960,7 +996,8 @@ ZOOM_options_set_int(opt, name, value)
     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>
@@ -1005,13 +1042,14 @@ ZOOM_options_set_int(opt, name, value)
     </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>
 
-    <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>
@@ -1050,13 +1088,14 @@ ZOOM_options_set_int(opt, name, value)
 
    </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>
 
-    <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>
@@ -1114,13 +1153,14 @@ ZOOM_options_set_int(opt, name, value)
     
    </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>
     
-    <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>
@@ -1143,13 +1183,14 @@ ZOOM_options_set_int(opt, name, value)
     </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>
     
-    <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>
@@ -1172,14 +1213,15 @@ ZOOM_options_set_int(opt, name, value)
     </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>
 
-   <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>
@@ -1258,7 +1300,8 @@ ZOOM_options_set_int(opt, name, value)
     (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>