-<!-- $Id: zoom.xml,v 1.21 2002-12-09 23:32:29 adam Exp $ -->
- <chapter id="zoom"><title>Building clients with ZOOM</title>
+<!-- $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
an initiative started by Mike Taylor (Mike is from the UK, which
provide a common Z39.50 client API not bound to a particular
programming language or toolkit.
</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.
+ </para>
+ </note>
+
<para>
The lack of a simple Z39.50 client API for &yaz; has become more
and more apparent over time. So when the first &zoom; specification
slash, the following part specifies a database for the connection.
</para>
<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.
+ </para>
+ <para>
Connection objects should be destroyed using the function
<function>ZOOM_connection_destroy</function>.
</para>
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>
of <function>ZOOM_connection_error</function> that is capable of
returning name of diagnostic set in <parameter>dset</parameter>.
</para>
- <sect2><title>Protocol behavior</title>
+ <sect2><title>Z39.50 Protocol behavior</title>
<para>
The calls <function>ZOOM_connection_new</function> and
<function>ZOOM_connection_connect</function> establishes a TCP/IP
API cannot tell the outcome (yet).
</para>
</sect2>
+ <sect2><title>SRW Protocol behavior</title>
+ <para>
+ 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>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.
+ </para>
+ <para>
+ The <literal>charset</literal> is used in the Content-Type header
+ of HTTP requests.
+ </para>
+ </sect2>
</sect1>
<sect1 id="zoom.query"><title>Queries</title>
<para>
int ZOOM_query_prefix(ZOOM_query q, const char *str);
+ int ZOOM_query_cql(ZOOM_query s, const char *str);
+
int ZOOM_query_sortby(ZOOM_query q, const char *criteria);
</synopsis>
<para>
and destroy them by calling <function>ZOOM_query_destroy</function>.
RPN-queries can be specified in <link linkend="PQF">PQF</link>
notation by using the
- function <function>ZOOM_query_prefix</function>. More
- query types will be added later, such as
+ function <function>ZOOM_query_prefix</function>.
+ The <function>ZOOM_query_cql</function> specifies a CQL
+ query to be sent to the server/target.
+ More query types will be added in future versions of &yaz;, such as
<link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
etc. In addition to a search, a sort criteria may be set. Function
<function>ZOOM_query_sortby</function> specifies a
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.
</tgroup>
</table>
<sect2>
- <title>Protocol behavior</title>
+ <title>Z39.50 Protocol behavior</title>
<para>
The creation of a result set involves at least a SearchRequest
- SearchResponse protocol handshake. Following that, if a sort
to specify one elementSetName option rather than three.
</para>
</sect2>
+ <sect2>
+ <title>SRW 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.
+ Since, the ZOOM driver does not save result set IDs any
+ present (retrieval) is transformed to a SRW SearchRetrieveRequest
+ with same query but, possibly, different offsets.
+ </para>
+ <para>
+ Option <literal>schema</literal> specifies SRW 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.
+ The remaining options
+ <literal>piggyback</literal>,
+ <literal>smallSetUpperBound</literal>,
+ <literal>largeSetLowerBound</literal>,
+ <literal>mediumSetPresentNumber</literal>,
+ <literal>mediumSetElementSetName</literal>,
+ <literal>smallSetElementSetName</literal> are
+ unsupported.
+ </para>
+ <para>
+ SRW 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.
+ </para>
+ <para>
+ Unfortunately, SRW 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).
+ </para>
+ </sect2>
</sect1>
<sect1 id="zoom.records"><title>Records</title>
<para>
<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>
</variablelist>
</para>
- <sect2><title>Protocol behavior</title>
+ <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
<function>ZOOM_resultset_records</function> inspects the client-side
<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>.
</para>
</sect2>
+ <sect2><title>SRW Protocol behavior</title>
+ <para>
+ The ZOOM driver for SRW treats records returned by a SRW server
+ as if they where Z39.50 records with transfer syntax XML and
+ no element set name or database name.
+ </para>
+ </sect2>
</sect1>
<sect1 id="zoom.scan"><title>Scan</title>
<para>
is the <literal>ZOOM_scanset</literal> which is a set of terms
returned by a target.
</para>
+
+ <para>
+ The Scan interface is Z39.50 only. SRW version 1.0 does not
+ support this.
+ </para>
+
<synopsis>
ZOOM_scanset ZOOM_connection_scan (ZOOM_connection c,
const char *startterm);
projects / yaz-moved-to-github.git / blobdiff