X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fzoom.xml;h=0ca1c8cc2e209db82781a00c07041199eb5e1ca2;hb=cf273cb8a7f73124935713928cd5df5b537f8b9c;hp=a9d97aef6a5bf8f7640889b31a0eaf109f039cd4;hpb=0718fd63660899964512631d1e246ded8e3d18d6;p=yaz-moved-to-github.git

diff --git a/doc/zoom.xml b/doc/zoom.xml
index a9d97ae..0ca1c8c 100644
--- a/doc/zoom.xml
+++ b/doc/zoom.xml
@@ -1,4 +1,4 @@
-<!-- $Id: zoom.xml,v 1.22 2003-02-21 00:24:26 adam Exp $ -->
+<!-- $Id: zoom.xml,v 1.31 2003-07-09 22:38:12 mike Exp $ -->
  <chapter id="zoom"><title>ZOOM</title>
   <para>
     &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is
@@ -11,8 +11,8 @@
   <note>
    <para>
     A recent addition to &yaz; is SRW support. You can now make
-    SRW ZOOM connections by specifying a new scheme for the
-    host name for a connection.
+    SRW ZOOM connections by specifying scheme <literal>http://</literal>
+    for the hostname for a connection.
    </para>
   </note>
 
@@ -167,6 +167,11 @@
         targetImplementationVersion</entry><entry> Implementation Version
         of target.
        </entry><entry>none</entry></row>
+      <row><entry>
+        databaseName</entry><entry>One or more database names
+        separated by character plus (<literal>+</literal>), which to
+        be used by subsequent search requests on this Connection.
+       </entry><entry>Default</entry></row>
      </tbody>
     </tgroup>
    </table>
@@ -233,16 +238,18 @@
     </sect2>
    <sect2><title>SRW Protocol behavior</title>
     <para>
-     The SRW protocol doesn't feature an Init Request, so
+     The SRW protocol doesn't feature an Inititialize Request, so
      the connection phase merely establishes a TCP/IP connection
      with the SOAP service.
     </para>
-    <para>None of the ZOOM connection options
+    <para>Most of the ZOOM connection options do not
      affect SRW and they are ignored. However, future versions
      of &yaz; might honor <literal>implementationName</literal> and
      put that as part of User-Agent header for HTTP requests.
-     The <literal>charset</literal>, and <literal>lang</literal>
-     might also affect HTTP headers in future releases.
+     </para>
+    <para>
+     The <literal>charset</literal> is used in the Content-Type header
+     of HTTP requests.
     </para>
    </sect2>
   </sect1>
@@ -353,6 +360,10 @@
         count</entry><entry>Number of records to be retrieved.
        </entry><entry>0</entry></row>
       <row><entry>
+        step</entry><entry>Number of records to be retrieved in
+        one chunk. The value, 0 means unchunked.
+       </entry><entry>0</entry></row>
+      <row><entry>
         elementSetName</entry><entry>Element-Set name of records. 
         Most targets should honor element set name <literal>B</literal>
         and <literal>F</literal> for brief and full respectively.
@@ -388,10 +399,6 @@
         The element set name to be for medium-sized result sets.
        </entry><entry>none</entry></row>
       <row><entry>
-        databaseName</entry><entry>One or more database names
-        separated by character plus (<literal>+</literal>).
-       </entry><entry>Default</entry></row>
-      <row><entry>
         setname</entry><entry>Name of Result Set (Result Set ID).
         If this option isn't set, the ZOOM module will automatically
         allocate a result set name.
@@ -544,30 +551,53 @@
     <function>ZOOM_record_get</function> is provided. The
     function returns a pointer to certain record information. The
     nature (type) of the pointer depends on the parameter,
-    <function>type</function>.
+    <parameter>type</parameter>.
+   </para>
+   <para>
+    The <parameter>type</parameter> is a string of the format:
+   </para>
+   <para>
+    <replaceable>form</replaceable>[; charset=<replaceable>from</replaceable>[,<replaceable>to</replaceable>]]
+   </para>
+   <para>
+    where <replaceable>form</replaceable> specifies the format of the
+    returned record, <replaceable>from</replaceable>
+    specifies the character set of the record in its original form
+    (as returned by the server), <replaceable>to</replaceable> specifies
+    the output (returned)
+    character set encoding.
+    If charset is not given, then no character set conversion takes place.
+    If <replaceable>to</replaceable> is omitted UTF-8 is assumed.
+   </para>
+   <para>
     In addition, for certain types, the length
     <literal>len</literal> passed will be set to the size in bytes of
-    the returned information.
+    the returned information. 
+    </para>
+   <para>
+    The following are the supported values for <replaceable>form</replaceable>.
     <variablelist>
      <varlistentry><term><literal>database</literal></term>
       <listitem><para>Database of record is returned
         as a C null-terminated string. Return type
         <literal>const char *</literal>. 
        </para></listitem>
-      </varlistentry>
+     </varlistentry>
      <varlistentry><term><literal>syntax</literal></term>
-      <listitem><para>The transfer syntax (OID) of the record is returned
-        as a C null-terminated string. Return type is
+      <listitem><para>The transfer syntax of the record is returned
+        as a C null-terminated string containing the symbolic name of
+	the record syntax, e.g. <literal>Usmarc</literal>. Return type
+	is
         <literal>const char *</literal>. 
        </para></listitem>
-      </varlistentry>
+     </varlistentry>
      <varlistentry><term><literal>render</literal></term>
       <listitem><para>The record is returned in a display friendly
         format. Upon completion buffer is returned
         (type <literal>const char *</literal>) and length is stored in
         <literal>*len</literal>.
        </para></listitem>
-      </varlistentry>
+     </varlistentry>
      <varlistentry><term><literal>raw</literal></term>
       <listitem><para>The record is returned in the internal
         YAZ specific format. For GRS-1, Explain, and others, the
@@ -578,9 +608,38 @@
         For SUTRS and octet aligned record (including all MARCs) the
         octet buffer is returned and the length of the buffer.
        </para></listitem>
-      </varlistentry>
+     </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
+	returned verbatim. MARC records are returned in
+	<ulink url="http://www.loc.gov/standards/marcxml/">
+	 MARCXML
+	 </ulink> 
+	(converted from ISO2709 to MARCXML by YAZ).
+	GRS-1 and OPAC records are not supported for this form.
+        Upon completion, the XML buffer is returned
+	(type <literal>const char *</literal>) and length is stored in
+        <literal>*len</literal>.
+       </para></listitem>
+     </varlistentry>
     </variablelist>
    </para>
+   <para>
+    Most
+    <ulink url="http://www.loc.gov/marc/">
+     MARC21
+    </ulink>
+    records uses the 
+    <ulink url="http://www.loc.gov/marc/specifications/speccharmarc8.html">
+     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>
     <para>
      The functions <function>ZOOM_resultset_record</function> and
@@ -594,7 +653,7 @@
     <para>
      There is a trick, however, in the usage of function
      <function>ZOOM_resultset_records</function> that allows for
-     delayed retrieval (and makes it non-blocking). By passing
+     delayed retrieval (and makes it non-blocking). By using
      a null pointer for <parameter>recs</parameter> you're indicating
      you're not interested in getting records objects
      <emphasis>now</emphasis>.