-<!-- $Id: zoom.xml,v 1.22 2003-02-21 00:24:26 adam Exp $ -->
+<!-- $Id: zoom.xml,v 1.32 2003-07-14 12:59:23 adam Exp $ -->
<chapter id="zoom"><title>ZOOM</title>
<para>
&zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is
<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>
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>
</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>
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.
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.
<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
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>
+ <varlistentry><term><literal>opac</literal></term>
+ <listitem><para>OPAC for record is returned in XML.
+ </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
<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>.