<chapter id="zoom">
- <!-- $Id: zoom.xml,v 1.1 2002-10-08 11:55:57 adam Exp $ -->
- <title>ZOOM</title>
- <para>
- About ZOOM (++).
- </para>
+ <!-- $Id: zoom.xml,v 1.5 2002-10-09 23:11:31 mike Exp $ -->
+ <title>ZOOM-C++</title>
+
+
+ <sect1 id="zoom-introduction">
+ <title>Introduction</title>
+ <para>
+ <ulink url="http://staging.zoom.z3950.org/">ZOOM</ulink>
+ is the emerging standard API for information retrieval programming
+ using the Z39.50 protocol. ZOOM's
+ <ulink url="http://staging.zoom.z3950.org/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://staging.zoom.z3950.org/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://staging.zoom.z3950.org/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>
+ from the Library of Congress's Z39.50 server:
+ </para>
+ <synopsis>
+ #include <iostream>
+ #include <yaz++/zoom.h>
+
+ using namespace ZOOM;
+
+ int main(int argc, char **argv)
+ {
+ connection conn("z3950.loc.gov", 7090);
+ conn.option("databaseName", "Voyager");
+ resultSet rs(conn, prefixQuery("@attr 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>
+ <para>
+ 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"/>
+ </para>
+ <para>
+ All of the classes defined by ZOOM-C++ are in the
+ <literal>ZOOM</literal> namespace. We will now consider
+ the five main classes in turn:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>connection</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>query</literal> and its subclasses
+ <literal>prefixQuery</literal> and
+ <literal>CCLQuery</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>resultSet</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>record</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>exception</literal> and its subclasses
+ <literal>systemException</literal>,
+ <literal>bib1Exception</literal> and
+ <literal>queryException</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect1>
+
+
+ <sect1 id="zoom-connection">
+ <title><literal>ZOOM::connection</literal></title>
+ <para>
+ A <literal>ZOOM::connection</literal> object represents an open
+ connection to a Z39.50 server. Such a connection is forged by
+ constructing a <literal>connection</literal> object.
+ </para>
+ <para>
+ The class has this declaration:
+ </para>
+ <synopsis>
+ class connection {
+ public:
+ connection (const char *hostname, int portnum);
+ ~connection ();
+ const char *option (const char *key) const;
+ const char *option (const char *key, const char *val);
+ };
+ </synopsis>
+ <para>
+ When a new <literal>connection</literal> is created, the hostname
+ and port number of a Z39.50 server must be supplied, and the
+ network connection is forged and wrapped in the new object. If the
+ connection can't be established - perhaps because the hostname
+ couldn't be resolved, or there is no server listening on the
+ specified port - then an
+ <link linkend="zoom-exception"><literal>exception</literal></link>
+ is thrown.
+ </para>
+ <para>
+ The only other methods on a <literal>connection</literal> object
+ are for getting and setting options. Any name-value pair of
+ strings may be set as options, and subsequently retrieved, but
+ certain options have special meanings which are understood by the
+ ZOOM code and affect the behaviour of the object that carries
+ them. For example, the value of the
+ <literal>databaseName</literal> option is used as the name of the
+ database to query when a search is executed against the
+ <literal>connection</literal>. For a full list of such special
+ options, see the ZOOM abstract API and the ZOOM-C documentation
+ (links below).
+ </para>
+
+ <sect2>
+ <title>References</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink url="http://staging.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="file:///usr/local/src/z39.50/yaz/doc/zoom.html#zoom.connections"
+ >The Connections section of the ZOOM-C documentation</ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+ </sect1>
+
+
+ <sect1 id="zoom-query">
+ <title><literal>ZOOM::query</literal> and subclasses</title>
+ <para>
+ The <literal>ZOOM::query</literal> class is a virtual base class,
+ representing a query to be submitted to a server. This class has
+ no methods, but two (so far) concrete subclasses, each implementing
+ a specific query notation.
+ </para>
+
+ <sect2>
+ <title><literal>ZOOM::prefixQuery</literal></title>
+ <para>
+ The class has this declaration:
+ </para>
+ <synopsis>
+ class prefixQuery : public query {
+ public:
+ prefixQuery (const char *pqn);
+ ~prefixQuery ();
+ };
+ </synopsis>
+ <para>
+ It enables a query to be created from Yaz's cryptic but
+ powerful
+ <ulink url="file:///usr/local/src/z39.50/yaz/doc/tools.html#PQF"
+ >Prefix Query Notation (PQN)</ulink>.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title><literal>ZOOM::CCLQuery</literal></title>
+ <para>
+ The class has this declaration:
+ </para>
+ <synopsis>
+ class CCLQuery : public query {
+ public:
+ CCLQuery (const char *ccl, void *qualset);
+ ~CCLQuery ();
+ };
+ </synopsis>
+ <para>
+ It enables a query to be created using the simpler but less
+ expressive
+ <ulink url="file:///usr/local/src/z39.50/yaz/doc/tools.html#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
+ documentation.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Discussion</title>
+ <para>
+ It will be readily recognised that these objects have no methods
+ other than their constructors: their only role in life is to be
+ used in searching, by being passed to the
+ <literal>resultSet</literal> class's constructor.
+ </para>
+ <para>
+ Given a suitable set of CCL qualifiers, the following pairs of
+ queries are equivalent:
+ </para>
+ <screen>
+ prefixQuery("dinosaur");
+ CCLQuery("dinosaur");
+
+ prefixQuery("@and complete dinosaur");
+ CCLQuery("complete and dinosaur");
+
+ prefixQuery("@and complete @or dinosaur pterosaur");
+ CCLQuery("complete and (dinosaur or pterosaur)");
+
+ prefixQuery("@attr 1=7 0253333490");
+ CCLQuery("isbn=0253333490");
+ </screen>
+ </sect2>
+
+ <sect2>
+ <title>References</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink url="http://staging.zoom.z3950.org/api/zoom-1.3.html#3.3"
+ >Section 3.3 (Query) of the ZOOM Abstract API</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="file:///usr/local/src/z39.50/yaz/doc/zoom.query.html"
+ >The Queries section of the ZOOM-C documentation</ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+ </sect1>
+
+
+ <sect1 id="zoom-resultset">
+ <title><literal>ZOOM::resultSet</literal></title>
+ <para>
+ A <literal>ZOOM::resultSet</literal> object represents a set of
+ records identified by a query that has been executed against a
+ particular connection. The sole purpose of both
+ <literal>connection</literal> and <literal>query</literal> objects
+ is that they can be used to create new
+ <literal>resultSet</literal>s - that is, to perform a search on the
+ server on the remote end of the connection.
+ </para>
+ <para>
+ The class has this declaration:
+ </para>
+ <synopsis>
+ class resultSet {
+ public:
+ resultSet (connection &c, const query &q);
+ ~resultSet ();
+ const char *option (const char *key) const;
+ const char *option (const char *key, const char *val);
+ size_t size () const;
+ const record *getRecord (size_t i) const;
+ };
+ </synopsis>
+ <para>
+ New <literal>resultSet</literal>s are created by the constructor,
+ which is passed a <literal>connection</literal>, indicating the
+ server on which the search is to be performed, and a
+ <literal>query</literal>, indicating what search to perform. If
+ the search fails - for example, because the query is malformed -
+ then an
+ <link linkend="zoom-exception"><literal>exception</literal></link>
+ is thrown.
+ </para>
+ <para>
+ Like <literal>connection</literal>s, <literal>resultSet</literal>
+ objects can carry name-value options. The special options which
+ affect ZOOM-C++'s behaviour are the same as those for ZOOM-C and
+ are described in its documentation (link below). In particular,
+ the <literal>preferredRecordSyntax</literal> option may be set to
+ a string such as ``USMARC'', ``SUTRS'' etc. to indicate what the
+ format in which records should be retrieved; and the
+ <literal>elementSetName</literal> option indicates whether brief
+ records (``B''), full records (``F'') or some other composition
+ should be used.
+ </para>
+ <para>
+ The <literal>size()</literal> method returns the number of records
+ in the result set. Zero is a legitimate value: a search that finds
+ no records is not the same as a search that fails.
+ </para>
+ <para>
+ Finally, the <literal>getRecord</literal> method returns the
+ <parameter>i</parameter>th record from the result set, where
+ <parameter>i</parameter> is zero-based: that is, legitmate values
+ range from zero up to one less than the result-set size.
+ </para>
+
+ <sect2>
+ <title>References</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink url="http://staging.zoom.z3950.org/api/zoom-1.3.html#3.4"
+ >Section 3.4 (Result Set) of the ZOOM Abstract API</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="file:///usr/local/src/z39.50/yaz/doc/zoom.resultsets.html"
+ >The Result Sets section of the ZOOM-C documentation</ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+ </sect1>
+
+
+ <sect1 id="zoom-record">
+ <title><literal>ZOOM::record</literal></title>
+ <para>
+ A <literal>ZOOM::record</literal> object represents a chunk of data
+ from a <literal>resultSet</literal> returned from a server.
+ </para>
+ <para>
+ The class has this declaration:
+ </para>
+ <synopsis>
+ class record {
+ public:
+ ~record ();
+ enum syntax {
+ UNKNOWN, GRS1, SUTRS, USMARC, UKMARC, XML
+ };
+ record *clone () const;
+ syntax recsyn () const;
+ const char *render () const;
+ const char *rawdata () const;
+ };
+ </synopsis>
+ <para>
+ ### discusson
+ </para>
+
+ <sect2>
+ <title>References</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink url="http://staging.zoom.z3950.org/api/zoom-1.3.html#3.5"
+ >Section 3.5 (Record) of the ZOOM Abstract API</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="file:///usr/local/src/z39.50/yaz/doc/zoom.records.html"
+ >The Records section of the ZOOM-C documentation</ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+ </sect1>
+
+
+ <sect1 id="zoom-exception">
+ <title><literal>ZOOM::exception</literal> and subclasses</title>
+ <para>
+ The <literal>ZOOM::exception</literal> class is a virtual base
+ class, representing a diagnostic generated by the ZOOM-C++ library
+ or returned from a server. ###
+ </para>
+ <synopsis>
+ class exception {
+ public:
+ exception (int code);
+ int errcode () const;
+ const char *errmsg () const;
+ };
+ </synopsis>
+ <para>
+ This class has three (so far) concrete subclasses:
+ </para>
+
+ <sect2>
+ <title><literal>ZOOM::systemException</literal></title>
+ <para>
+ The class has this declaration:
+ </para>
+ <synopsis>
+ class systemException: public exception {
+ public:
+ systemException ();
+ int errcode () const;
+ const char *errmsg () const;
+ };
+ </synopsis>
+ </sect2>
+
+ <sect2>
+ <title><literal>ZOOM::bib1Exception</literal></title>
+ <para>
+ The class has this declaration:
+ </para>
+ <synopsis>
+ class bib1Exception: public exception {
+ public:
+ bib1Exception (int errcode, const char *addinfo);
+ int errcode () const;
+ const char *errmsg () const;
+ const char *addinfo () const;
+ };
+ </synopsis>
+ </sect2>
+
+ <sect2>
+ <title><literal>ZOOM::queryException</literal></title>
+ <para>
+ The class has this declaration:
+ </para>
+ <synopsis>
+ class queryException: public exception {
+ public:
+ static const int PREFIX = 1;
+ static const int CCL = 2;
+ queryException (int qtype, const char *source);
+ int errcode () const;
+ const char *errmsg () const;
+ const char *addinfo () const;
+ };
+ </synopsis>
+ </sect2>
+
+ <sect2>
+ <title>Discussion</title>
+ <para>
+ ### discusson
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>References</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink url="http://staging.zoom.z3950.org/api/zoom-1.3.html#3.7"
+ >Section 3.7 (Exception) of the ZOOM Abstract API</ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Because C does not support exceptions, ZOOM-C has no API element
+ that corresponds directly with ZOOM-C++'s
+ <literal>exception</literal> class and its subclasses. The
+ closest thing is the <literal>ZOOM_connection_error</literal>
+ function described in
+ <ulink url="file:///usr/local/src/z39.50/yaz/doc/zoom.html#zoom.connections"
+ >The Connections section</ulink> of the documentation.
+ </para>
+ </sect2>
+ </sect1>
+
</chapter>
+
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
projects / yazpp-moved-to-github.git / blobdiff