Add the promised sample program with error checking.

[yazpp-moved-to-github.git] / doc / zoom.xml

<chapter id="zoom">
 <!-- $Id: zoom.xml,v 1.7 2002-10-11 12:19:09 mike Exp $ -->
 <title>ZOOM-C++</title>


 <sect1 id="zoom-introduction">
  <title>Introduction</title>
  <para>
   <ulink url="http://zoom.z3950.org/">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>
   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>
   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>
   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
   <citetitle>The Complete Dinosaur</citetitle>
   from the Library of Congress's Z39.50 server:
  </para>
  <programlisting>
    #include &lt;iostream&gt;
    #include &lt;yaz++/zoom.h&gt;

    using namespace ZOOM;

    int main(int argc, char **argv)
    {
        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 &lt;&lt; rec-&gt;render() &lt;&lt; endl;
    }
  </programlisting>
  <para>
   (Note that, 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>
  <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://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>


 <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>
   <synopsis>
    class prefixQuery : public query {
    public:
      prefixQuery (const char *pqn);
      ~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>
   <title><literal>ZOOM::CCLQuery</literal></title>
   <synopsis>
    class CCLQuery : public query {
    public:
      CCLQuery (const char *ccl, void *qualset);
      ~CCLQuery ();
    };
   </synopsis>
   <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>.
    The qualifiers recognised by the CCL parser are specified in an
    external configuration file in the format described by the Yaz
    documentation.
   </para>
   <para>
    If query construction fails for either type of
    <literal>query</literal> object - typically because the query
    string itself is not valid PQN or CCL - then an
    <link linkend="zoom-exception"><literal>exception</literal></link>
    is thrown.
   </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://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="http://www.indexdata.dk/yaz/doc/zoom.query.php"
        >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 &amp;c, const query &amp;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 uses attributes
   that the server doesn't implement - 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.  If the
   method fails, for example because the requested record is out of
   range, it <literal>throw</literal>s an
   <link linkend="zoom-exception"><literal>exception</literal></link>.
  </para>

  <sect2>
   <title>References</title>
   <itemizedlist>
    <listitem>
     <para>
      <ulink url="http://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="http://www.indexdata.dk/yaz/doc/zoom.resultsets.php"
        >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>
   Records returned from Z39.50 servers are encoded using a record
   syntax: the various national MARC formats are commonly used for
   bibliographic data, GRS-1 or XML for complex structured data, SUTRS
   for simple human-readable text, etc.  The
   <literal>record::syntax</literal> enumeration specifies constants
   representing common record syntaxes, and the
   <literal>recsyn()</literal> method returns the value corresponding
   to the record-syntax of the record on which it is invoked.
   <note>
    <para>
     Because this interface uses an enumeration, it is difficult to
     extend to other record syntaxes - for example, DANMARC, the MARC
     variant widely used in Denmark.  We might either grow the
     enumeration substantially, or change the interface to return
     either an integer or a string.
    </para>
   </note>
  </para>
  <para>
   The simplest thing to do with a retrieved record is simply to
   <literal>render()</literal> it.  This returns a human-readable, but
   not necessarily very pretty, representation of the contents of the
   record.  This is useful primarily for testing and debugging, since
   the application has no control over how the record appears.
   (The application must <emphasis>not</emphasis>
   <literal>delete</literal> the returned string - it is ``owned'' by
   the record object.)
  </para>
  <para>
   More sophisticated applications will want to deal with the raw data
   themselves: the <literal>rawdata()</literal> method returns it.
   Its format will vary depending on the record syntax: SUTRS, MARC
   and XML records are returned ``as is'', and GRS-1 records as a
   pointer to their top-level node, which is a
   <literal>Z_GenericRecord</literal> structure as defined in the
   <literal>&lt;yaz/z-grs.h&gt;</literal> header file.
   (The application must <emphasis>not</emphasis>
   <literal>delete</literal> the returned data - it is ``owned'' by
   the record object.)
  </para>
  <para>
   Perceptive readers will notice that there are no methods for access
   to individual fields within a record.  That's because the different
   record syntaxes are so different that there is no even a uniform
   notion of what a field is across them all, let alone a sensible way
   to implement such a function.  Fetch the raw data instead, and pick
   it apart ``by hand''.
  </para>

  <sect2>
   <title>Memory Management</title>
   <para>
    The <literal>record</literal> obejcts 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
    <literal>record</literal> is automatically deallocated when the
    <literal>resultSet</literal> that owns it is
    <literal>delete</literal>d.
   </para>
   <para>
    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>
   <programlisting>
    resultSet rs(conn, query);
    cout &lt;&lt; rs.getRecord(0)-&gt;render();
   </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
    fetched.  In this case, the <literal>clone(f)</literal> method can
    be used to make an autonomous copy.  The application must
    <literal>delete</literal> it when it doesn't need it any longer:
   </para>
   <programlisting>
    record *rec;
    {
        resultSet rs(conn, query);
        rec = rs.getRecord(0)-&gt;clone();
        // `rs' goes out of scope here, and is deleted
    }
    cout &lt;&lt; rec-&gt;render();
    delete rec;
   </programlisting>
  </sect2>

  <sect2>
   <title>References</title>
   <itemizedlist>
    <listitem>
     <para>
      <ulink url="http://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="http://www.indexdata.dk/yaz/doc/zoom.records.php"
        >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.  Its subclasses represent particular
   kinds of error.
  </para>
  <para>
   When any of the ZOOM methods fail, they respond by
   <literal>throw</literal>ing an object of type
   <literal>exception</literal> or one of its subclasses.  This most
   usually happens with the <literal>connection</literal> constructor,
   the various query constructors, the <literal>resultSet</literal>
   constructor (which is actually the searching method) and
   <literal>resultSet::getRecord()</literal>.
  </para>
  <para>
    The base class has this declaration:
  </para>
  <synopsis>
    class exception {
    public:
      exception (int code);
      int errcode () const;
      const char *errmsg () const;
    };
  </synopsis>
  <para>
   It has three concrete subclasses:
  </para>

  <sect2>
   <title><literal>ZOOM::systemException</literal></title>
   <synopsis>
    class systemException: public exception {
    public:
      systemException ();
      int errcode () const;
      const char *errmsg () const;
    };
   </synopsis>
   <para>
    Represents a ``system error'', typically indicating that a system
    call failed - often in the low-level networking code that
    underlies Z39.50.  <literal>errcode()</literal> returns the value
    that the system variable <literal>errno</literal> had at the time
    the exception was constructed; and <literal>errmsg()</literal>
    returns a human-readable error-message corresponidng to that error
    code.
   </para>
  </sect2>

  <sect2>
   <title><literal>ZOOM::bib1Exception</literal></title>
   <synopsis>
    class bib1Exception: public exception {
    public:
      bib1Exception (int errcode, const char *addinfo);
      int errcode () const;
      const char *errmsg () const;
      const char *addinfo () const;
    };
   </synopsis>
   <para>
    Represents an error condition communicated by a Z39.50 server.
    <literal>errcode()</literal> returns the BIB-1 diagnostic code of
    the error, and <literal>errmsg()</literal> a human-readable error
    message corresponding to that code.  <literal>addinfo()</literal>
    returns any additional information associated with the error.
   </para>
   <para>
    For example, if a ZOOM application tries to search in the
    ``Voyager'' database of a server that does not have a database of
    that name, a <literal>bib1Exception</literal> will be thrown in
    which <literal>errcode()</literal> returns 109,
    <literal>errmsg()</literal> returns the corresponding error
    message ``Database unavailable'' and <literal>addinfo()</literal>
    returns the name of the requested, but unavailable, database.
   </para>
  </sect2>

  <sect2>
   <title><literal>ZOOM::queryException</literal></title>
   <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>
   <para>
    This class represents an error in parsing a query into a form that
    a Z39.50 can understand.  It must be created with the
    <literal>qtype</literal> parameter equal to one of the query-type
    constants, which can be retrieved via the
    <literal>errcode()</literal> method; <literal>errmsg()</literal>
    returns an error-message specifying which kind of query was
    malformed; and <literal>addinfo()</literal> returns a copy of the
    query itself (that is, the value of <literal>source</literal> with
    which the exception object was created.)
   </para>
  </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 -lyaz++ -lyaz */

    #include &lt;iostream&gt;
    #include &lt;yaz++/zoom.h&gt;

    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 &lt;&lt; rec-&gt;render() &lt;&lt; endl;
        } catch (systemException &amp;e) {
            cerr &lt;&lt; "System error " &lt;&lt;
                e.errcode() &lt;&lt; " (" &lt;&lt; e.errmsg() &lt;&lt; ")" &lt;&lt; endl;
        } catch (bib1Exception &amp;e) {
            cerr &lt;&lt; "BIB-1 error " &lt;&lt; 
                e.errcode() &lt;&lt; " (" &lt;&lt; e.errmsg() &lt;&lt; "): " &lt;&lt; e.addinfo() &lt;&lt; endl;
        } catch (queryException &amp;e) {
            cerr &lt;&lt; "Query error " &lt;&lt;
                e.errcode() &lt;&lt; " (" &lt;&lt; e.errmsg() &lt;&lt; "): " &lt;&lt; e.addinfo() &lt;&lt; endl;
        } catch (exception &amp;e) {
            cerr &lt;&lt; "Error " &lt;&lt;
                e.errcode() &lt;&lt; " (" &lt;&lt; e.errmsg() &lt;&lt; ")" &lt;&lt; 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>
   <title>References</title>
   <itemizedlist>
    <listitem>
     <para>
      <ulink url="http://zoom.z3950.org/api/zoom-1.3.html#3.7"
        >Section 3.7 (Exception) of the ZOOM Abstract API</ulink>
     </para>
    </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.
     </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="http://www.indexdata.dk/yaz/doc/zoom.php#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
 sgml-omittag:t
 sgml-shorttag:t
 sgml-minimize-attributes:nil
 sgml-always-quote-attributes:t
 sgml-indent-step:1
 sgml-indent-data:t
 sgml-parent-document: "zebra.xml"
 sgml-local-catalogs: nil
 sgml-namecase-general:t
 End:
 -->