-<!-- $Id: zoom.xml,v 1.20 2002-09-25 20:32:53 adam Exp $ -->
- <chapter id="zoom"><title>Building clients with ZOOM</title>
-
+<!-- $Id: zoom.xml,v 1.25 2003-05-12 22:38:40 adam 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
<ulink url="http://zoom.z3950.org/">ZOOM web-site</ulink> for
more information.
</para>
-
+
<para>
In order to fully understand this chapter you should read and
try the example programs <literal>zoomtst1.c</literal>,
<literal>zoomtst2.c</literal>, .. in the <literal>zoom</literal>
directory.
</para>
-
+
<para>
The C language misses features found in object oriented languages
such as C++, Java, etc. For example, you'll have to manually,
<para>The Connection object is a session with a target.
</para>
<synopsis>
- #include <yaz/zoom.h>
+ #include <yaz/zoom.h>
- ZOOM_connection ZOOM_connection_new (const char *host, int portnum);
+ ZOOM_connection ZOOM_connection_new (const char *host, int portnum);
- ZOOM_connection ZOOM_connection_create (ZOOM_options options);
-
- void ZOOM_connection_connect(ZOOM_connection c, const char *host,
+ ZOOM_connection ZOOM_connection_create (ZOOM_options options);
+
+ void ZOOM_connection_connect(ZOOM_connection c, const char *host,
int portnum);
- void ZOOM_connection_destroy (ZOOM_connection c);
+ void ZOOM_connection_destroy (ZOOM_connection c);
</synopsis>
<para>
Connection objects are created with either function
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>
The <function>ZOOM_connection_option_set</function> allows you to
set an option given by <parameter>key</parameter> to the value
<parameter>value</parameter> for the connection.
- Function <function>ZOOM_connection_option_get</function> returns
+ Function <function>ZOOM_connection_option_get</function> returns
the value for an option given by <parameter>key</parameter>.
</para>
<table frame="top"><title>ZOOM Connection Options</title>
</entry><entry>none</entry></row>
<row><entry>
pass</entry><entry>Authentication password
- </entry><entry>none</entry></row>
+ </entry><entry>none</entry></row>
<row><entry>
host</entry><entry>Target host. This setting is "read-only".
It's automatically set internally when connecting to a target.
<row><entry>
charset</entry><entry> Character set for negotiation.
</entry><entry>none</entry></row>
+ <row><entry>
+ targetImplementationId</entry><entry> Implementation ID of target.
+ </entry><entry>none</entry></row>
+ <row><entry>
+ targetImplementationName</entry><entry> Implementation Name of target.
+ </entry><entry>none</entry></row>
+ <row><entry>
+ 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>
</para>
<synopsis>
int ZOOM_connection_error (ZOOM_connection c, const char **cp,
- const char **addinfo);
+ const char **addinfo);
+ int ZOOM_connection_error_x (ZOOM_connection c, const char **cp,
+ const char **addinfo, const char **dset);
</synopsis>
<para>
- Use <function>ZOOM_connection_error</function> to check for
+ Function <function>ZOOM_connection_error</function> checks for
errors for the last operation(s) performed. The function returns
zero if no errors occurred; non-zero otherwise indicating the error.
Pointers <parameter>cp</parameter> and <parameter>addinfo</parameter>
holds messages for the error and additional-info if passed as
- non-<literal>NULL</literal>.
+ non-<literal>NULL</literal>. Function
+ <function>ZOOM_connection_error_x</function> is an extended version
+ 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 Init Request, so
+ the connection phase merely establishes a TCP/IP connection
+ with the SOAP service.
+ </para>
+ <para>None of the ZOOM connection options
+ 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>
+ </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
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>
</varlistentry>
</variablelist>
</para>
- <sect2><title>Protocol behavior</title>
+ <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
<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);