<chapter id="zoom">
- <!-- $Id: zoom.xml,v 1.6 2002-10-10 22:48:10 mike Exp $ -->
+ <!-- $Id: zoom.xml,v 1.17 2006-10-10 21:59:43 adam Exp $ -->
<title>ZOOM-C++</title>
<sect1 id="zoom-introduction">
<title>Introduction</title>
<para>
- <ulink url="http://zoom.z3950.org/">ZOOM</ulink>
+ <ulink url="&url.zoom;">ZOOM</ulink>
is the emerging standard API for information retrieval programming
using the Z39.50 protocol. ZOOM's
- <ulink url="http://zoom.z3950.org/api/">Abstract API</ulink>
+ <ulink url="&url.zoom.api;">Abstract API</ulink>
specifies semantics for classes representing key IR concepts such as
connections, queries, result sets and records; and there are various
- <ulink url="http://zoom.z3950.org/bind/">bindings</ulink>
+ <ulink url="&url.zoom.bind;">bindings</ulink>
specifying how those concepts should be represented in various
programming languages.
</para>
<para>
- The Yaz++ library includes an implementation of the <ulink
- url="http://zoom.z3950.org/bind/cplusplus/"
- >C++ binding</ulink>
+ The YAZ++ library includes an implementation of the <ulink
+ url="&url.zoom.bind.cplusplus;">C++ binding</ulink>
for ZOOM, enabling quick, easy development of client applications.
</para>
<para>
For example, here is a tiny Z39.50 client that fetches and displays
- the MARC record for Farlow & Brett Surman's
- <!-- ### there must be a better way to mark up a book title? -->
- <emphasis>The Complete Dinosaur</emphasis>
+ the MARC record for Farlow & Brett Surman's
+ <citetitle>The Complete Dinosaur</citetitle>
from the Library of Congress's Z39.50 server:
</para>
- <synopsis>
+ <programlisting>
#include <iostream>
- #include <yaz++/zoom.h>
+ #include <yazpp/zoom.h>
using namespace ZOOM;
{
connection conn("z3950.loc.gov", 7090);
conn.option("databaseName", "Voyager");
- resultSet rs(conn, prefixQuery("@attr attr 1=7 0253333490"));
+ conn.option("preferredRecordSyntax", "USMARC");
+ resultSet rs(conn, prefixQuery("@attr 1=7 0253333490"));
const record *rec = rs.getRecord(0);
cout << rec->render() << endl;
}
- </synopsis>
- <para>
- (Note that, for the sake of simplicity, this does not check for
- errors: we show a more realistic version of this program later.)
- </para>
+ </programlisting>
+ <note>
+ <para>
+ For the sake of simplicity, this program does not check
+ for errors: we show a more robust version of the same program
+ <link linkend="revised-sample">later</link>.)
+ </para>
+ </note>
<para>
- Yaz++'s implementation of the C++ binding is a thin layer over Yaz's
+ YAZ++'s implementation of the C++ binding is a thin layer over YAZ's
implementation of the C binding. For information on the supported
options and other such details, see the ZOOM-C documentation, which
can be found on-line at
- <ulink url="http://www.indexdata.dk/yaz/doc/zoom.php"/>
+ <ulink url="&url.yaz.zoom;"/>
</para>
<para>
All of the classes defined by ZOOM-C++ are in the
(links below).
</para>
- <sect2>
+ <sect2 id="connection.references">
<title>References</title>
<itemizedlist>
<listitem>
<para>
<ulink url="http://zoom.z3950.org/api/zoom-1.3.html#3.2"
>Section 3.2 (Connection) of the ZOOM Abstract API</ulink>
- </para>
- </listitem>
- <listitem>
- <para>
- <ulink url="http://www.indexdata.dk/yaz/doc/zoom.php#zoom.connections"
- >The Connections section of the ZOOM-C documentation</ulink>
- </para>
- </listitem>
- </itemizedlist>
- </sect2>
- </sect1>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="&url.yaz.zoom.connections;"
+ >The Connections section f the ZOOM-C documentation</ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+ </sect1>
<sect1 id="zoom-query">
a specific query notation.
</para>
- <sect2>
+ <sect2 id="ZOOM::prefixQuery">
<title><literal>ZOOM::prefixQuery</literal></title>
<synopsis>
class prefixQuery : public query {
~prefixQuery ();
};
</synopsis>
- <para>
- This class enables a query to be created by compiling Yaz's
- cryptic but powerful
- <ulink url="http://www.indexdata.dk/yaz/doc/tools.php#PQF"
- >Prefix Query Notation (PQN)</ulink>.
- </para>
- </sect2>
-
- <sect2>
+ <para>
+ This class enables a query to be created by compiling YAZ's
+ cryptic but powerful
+ <ulink url="&url.yaz.pqf;">Prefix Query Notation (PQN)</ulink>.
+ </para>
+ </sect2>
+
+ <sect2 id="ZOOM::CCLQuery">
<title><literal>ZOOM::CCLQuery</literal></title>
<synopsis>
class CCLQuery : public query {
<para>
This class enables a query to be created using the simpler but
less expressive
- <ulink url="http://www.indexdata.dk/yaz/doc/tools.php#CCL"
- >Common Command Language (CCL)</ulink>.
+ <ulink url="&url.yaz.ccl;">Common Command Language (CCL)</ulink>.
The qualifiers recognised by the CCL parser are specified in an
- external configuration file in the format described by the Yaz
+ external configuration file in the format described by the YAZ
documentation.
</para>
<para>
</para>
</sect2>
- <sect2>
+ <sect2 id="queries.discussion">
<title>Discussion</title>
<para>
It will be readily recognised that these objects have no methods
</screen>
</sect2>
- <sect2>
+ <sect2 id="query.references">
<title>References</title>
<itemizedlist>
<listitem>
</listitem>
<listitem>
<para>
- <ulink url="http://www.indexdata.dk/yaz/doc/zoom.query.php"
+ <ulink url="&url.yaz.zoom.query;"
>The Queries section of the ZOOM-C documentation</ulink>
</para>
</listitem>
<link linkend="zoom-exception"><literal>exception</literal></link>.
</para>
- <sect2>
+ <sect2 id="resultset.references">
<title>References</title>
<itemizedlist>
<listitem>
</listitem>
<listitem>
<para>
- <ulink url="http://www.indexdata.dk/yaz/doc/zoom.resultsets.php"
+ <ulink url="&url.yaz.zoom.resultsets;"
>The Result Sets section of the ZOOM-C documentation</ulink>
</para>
</listitem>
it apart ``by hand''.
</para>
- <sect2>
+ <sect2 id="zoom.memory.management">
<title>Memory Management</title>
<para>
- The <literal>record</literal> obejcts returned from
+ The <literal>record</literal> objects returned from
<literal>resultSet::getRecord()</literal> are ``owned'' by the
result set object: that means that the application is not
responsible for <literal>delete</literal>ing them - each
Usually that's what you want: it means that you can easily fetch a
record, use it and forget all about it, like this:
</para>
- <screen>
+ <programlisting>
resultSet rs(conn, query);
cout << rs.getRecord(0)->render();
- </screen>
+ </programlisting>
<para>
But sometimes you want a <literal>record</literal> to live on past
the lifetime of the <literal>resultSet</literal> from which it was
be used to make an autonomous copy. The application must
<literal>delete</literal> it when it doesn't need it any longer:
</para>
- <screen>
+ <programlisting>
record *rec;
{
resultSet rs(conn, query);
}
cout << rec->render();
delete rec;
- </screen>
+ </programlisting>
</sect2>
- <sect2>
+ <sect2 id="record.references">
<title>References</title>
<itemizedlist>
<listitem>
</listitem>
<listitem>
<para>
- <ulink url="http://www.indexdata.dk/yaz/doc/zoom.records.php"
+ <ulink url="&url.yaz.zoom.records;"
>The Records section of the ZOOM-C documentation</ulink>
</para>
</listitem>
It has three concrete subclasses:
</para>
- <sect2>
+ <sect2 id="ZOOM::systemException">
<title><literal>ZOOM::systemException</literal></title>
<synopsis>
class systemException: public exception {
</para>
</sect2>
- <sect2>
+ <sect2 id="ZOOM::bib1Exception">
<title><literal>ZOOM::bib1Exception</literal></title>
<synopsis>
class bib1Exception: public exception {
</para>
</sect2>
- <sect2>
+ <sect2 id="ZOOM::queryException">
<title><literal>ZOOM::queryException</literal></title>
<synopsis>
class queryException: public exception {
</para>
</sect2>
- <sect2>
+ <sect2 id="revised-sample">
+ <title>Revised Sample Program</title>
+ <para>
+ Now we can revise the sample program from the
+ <link linkend="zoom-introduction">introduction</link>
+ to catch exceptions and report any errors:
+ </para>
+ <programlisting>
+ /* g++ -o zoom-c++-hw zoom-c++-hw.cpp -lzoompp -lyaz */
+
+ #include <iostream>
+ #include <yazpp/zoom.h>
+
+ using namespace ZOOM;
+
+ int main(int argc, char **argv)
+ {
+ try {
+ connection conn("z3950.loc.gov", 7090);
+ conn.option("databaseName", "Voyager");
+ conn.option("preferredRecordSyntax", "USMARC");
+ resultSet rs(conn, prefixQuery("@attr 1=7 0253333490"));
+ const record *rec = rs.getRecord(0);
+ cout << rec->render() << endl;
+ } catch (systemException &e) {
+ cerr << "System error " <<
+ e.errcode() << " (" << e.errmsg() << ")" << endl;
+ } catch (bib1Exception &e) {
+ cerr << "BIB-1 error " <<
+ e.errcode() << " (" << e.errmsg() << "): " << e.addinfo() << endl;
+ } catch (queryException &e) {
+ cerr << "Query error " <<
+ e.errcode() << " (" << e.errmsg() << "): " << e.addinfo() << endl;
+ } catch (exception &e) {
+ cerr << "Error " <<
+ e.errcode() << " (" << e.errmsg() << ")" << endl;
+ }
+ }
+ </programlisting>
+ <para>
+ The heart of this program is the same as in the original version,
+ but it's now wrapped in a <literal>try</literal> block followed by
+ several <literal>catch</literal> blocks which try to give helpful
+ diagnostics if something goes wrong.
+ </para>
+ <para>
+ The first such block diagnoses system-level errors such as memory
+ exhaustion or a network connection being broken by a server's
+ untimely death; the second catches errors at the Z39.50 level,
+ such as a server's report that it can't provide records in USMARC
+ syntax; the third is there in case there's something wrong with
+ the syntax of the query (although in this case it's correct); and
+ finally, the last <literal>catch</literal> block is a
+ belt-and-braces measure to be sure that nothing escapes us.
+ </para>
+ </sect2>
+
+ <sect2 id="exception.references">
<title>References</title>
<itemizedlist>
<listitem>
</listitem>
<listitem>
<para>
- <ulink url="http://lcweb.loc.gov/z3950/agency/defns/bib1diag.html"
- >Bib-1 Diagnostics</ulink> on the
- <ulink url="http://lcweb.loc.gov/z3950/agency/"
- >Z39.50 Maintenance Agency</ulink> site.
+ <ulink url="&url.z39.50.diagnostics;">Bib-1 Diagnostics</ulink> on the
+ <ulink url="&url.z39.50;">Z39.50 Maintenance Agency</ulink> site.
</para>
</listitem>
</itemizedlist>
<literal>exception</literal> class and its subclasses. The
closest thing is the <literal>ZOOM_connection_error</literal>
function described in
- <ulink url="http://www.indexdata.dk/yaz/doc/zoom.php#zoom.connections"
+ <ulink url="&url.yaz.zoom.connections;"
>The Connections section</ulink> of the documentation.
</para>
</sect2>
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
- sgml-parent-document: "zebra.xml"
+ sgml-parent-document: "yazpp.xml"
sgml-local-catalogs: nil
sgml-namecase-general:t
End: