doc/zoom.xml

   1 <chapter id="zoom">
   2  <!-- $Id: zoom.xml,v 1.3 2002-10-09 09:07:10 mike Exp $ -->
   3  <title>ZOOM-C++</title>
   4
   5  <sect1 id="zoom.introduction">
   6   <title>Introduction</title>
   7   <para>
   8    <ulink url="http://staging.zoom.z3950.org/">ZOOM</ulink>
   9    is the emerging standard API for information retrieval programming
  10    using the Z39.50 protocol.  ZOOM's
  11    <ulink url="http://staging.zoom.z3950.org/api/">Abstract API</ulink>
  12    specifies semantics for classes representing key IR concepts such as
  13    connections, queries, result sets and records; and there are various
  14    <ulink url="http://staging.zoom.z3950.org/bind/">bindings</ulink>
  15    specifying how those concepts should be represented in various
  16    programming languages.
  17   </para>
  18   <para>
  19    The Yaz++ library includes an implementation of the <ulink
  20    url="http://staging.zoom.z3950.org/bind/cplusplus/"
  21         >C++ binding</ulink>
  22    for ZOOM, enabling quick, easy development of client applications.
  23   </para>
  24   <para>
  25    For example, here is a tiny Z39.50 client that fetches and displays
  26    the MARC record for Farlow & Brett Surman's
  27    <!-- ### there must be a better way to mark up a book title? -->
  28    <emphasis>The Complete Dinosaur</emphasis>
  29    from the Library of Congress's Z39.50 server:
  30    <screen>
  31     #include &lt;iostream&gt;
  32     #include &lt;yaz++/zoom.h&gt;
  33
  34     using namespace ZOOM;
  35
  36     int main(int argc, char **argv)
  37     {
  38         connection conn("z3950.loc.gov", 7090);
  39         conn.option("databaseName", "Voyager");
  40         resultSet rs(conn, prefixQuery("@attr attr 1=7 0253333490"));
  41         const record *rec = rs.getRecord(0);
  42         cout &lt;&lt; rec-&gt;render() &lt;&lt; endl;
  43     }
  44    </screen>
  45    (Note that, for the sake of simplicity, this does not check for
  46    errors: we show a more realistic version of this program later.)
  47   </para>
  48   <para>
  49    Yaz++'s implementation of the C++ binding is a thin layer over Yaz's
  50    implementation of the C binding.  For information on the supported
  51    options and other such details, see the ZOOM-C documentation, which
  52    can be found on-line at
  53    <ulink url="http://www.indexdata.dk/yaz/doc/zoom.php"/>
  54   </para>
  55   <para>
  56    All of the classes defined by ZOOM-C++ are in the
  57    <literal>ZOOM</literal> namespace.  We will now consider
  58    the five main classes in turn:
  59
  60    <itemizedlist>
  61     <listitem>
  62      <para>
  63       <literal>connection</literal>
  64      </para>
  65     </listitem>
  66
  67     <listitem>
  68      <para>
  69       <literal>query</literal> and its subclasses
  70       <literal>prefixQuery</literal> and
  71       <literal>CCLQuery</literal>
  72      </para>
  73     </listitem>
  74
  75     <listitem>
  76      <para>
  77       <literal>resultSet</literal>
  78      </para>
  79     </listitem>
  80
  81     <listitem>
  82      <para>
  83       <literal>record</literal>
  84      </para>
  85     </listitem>
  86
  87     <listitem>
  88      <para>
  89       <literal>exception</literal> and its subclasses
  90       <literal>systemException</literal>,
  91       <literal>bib1Exception</literal> and
  92       <literal>queryException</literal>
  93      </para>
  94     </listitem>
  95    </itemizedlist>
  96   </para>
  97  </sect1>
  98
  99  <sect1>
 100   <title><literal>ZOOM::connection</literal></title>
 101   <para>
 102    SEE ALSO
 103    <ulink url="http://staging.zoom.z3950.org/api/zoom-1.3.html#3.2"
 104         >Section 3.2 (Connection) of the ZOOM Abstract API</ulink>
 105   </para>
 106   <para>
 107    A <literal>ZOOM::connection</literal> object represents an open
 108    connection to a Z39.50 server.  Such a connection is forged by
 109    constructing a <literal>connection</literal> object.
 110   </para>
 111   <para>
 112    The class has this declaration:
 113    <screen>
 114     class connection {
 115     public:
 116       connection (const char *hostname, int portnum);
 117       ~connection ();
 118       const char *option (const char *key) const;
 119       const char *option (const char *key, const char *val);
 120     };
 121    </screen>
 122   </para>
 123   <para>
 124    ### discusson
 125   </para>
 126  </sect1>
 127
 128  <sect1>
 129   <title><literal>ZOOM::query</literal> and subclasses</title>
 130   <para>
 131    SEE ALSO
 132    <ulink url="http://staging.zoom.z3950.org/api/zoom-1.3.html#3.3"
 133         >Section 3.3 (Query) of the ZOOM Abstract API</ulink>
 134   </para>
 135   <para>
 136    The <literal>ZOOM::query</literal> class is a virtual base class,
 137    representing a query to be submitted to a server.  This class has
 138    no methods, but two (so far) concrete subclasses:
 139   </para>
 140
 141   <sect2>
 142    <title><literal>ZOOM::prefixQuery</literal></title>
 143    <para>
 144     The class has this declaration:
 145     <screen>
 146     class prefixQuery : public query {
 147     public:
 148       prefixQuery (const char *pqn);
 149       ~prefixQuery ();
 150     };
 151     </screen>
 152    </para>
 153   </sect2>
 154
 155   <sect2>
 156    <title><literal>ZOOM::CCLQuery</literal></title>
 157    <para>
 158     The class has this declaration:
 159     <screen>
 160     class CCLQuery : public query {
 161     public:
 162       CCLQuery (const char *ccl, void *qualset);
 163       ~CCLQuery ();
 164     };
 165     </screen>
 166    </para>
 167   </sect2>
 168
 169   <sect2>
 170    <title>Discussion</title>
 171    <para>
 172     It will be readily recognised that these objects have no methods
 173     other than their constructors: their only role in life is to be
 174     used in searching, by being passed to the
 175     <literal>resultSet</literal> class's constructor.
 176    </para>
 177    <para>
 178     ### discusson
 179    </para>
 180   </sect2>
 181  </sect1>
 182
 183  <sect1>
 184   <title><literal>ZOOM::resultSet</literal></title>
 185   <para>
 186    SEE ALSO
 187    <ulink url="http://staging.zoom.z3950.org/api/zoom-1.3.html#3.4"
 188         >Section 3.4 (Result Set) of the ZOOM Abstract API</ulink>
 189   </para>
 190   <para>
 191    A <literal>ZOOM::resultSet</literal> object represents a set of
 192    record identified by a query that has been executed against a
 193    particular connection.
 194   </para>
 195   <para>
 196    The class has this declaration:
 197    <screen>
 198     class resultSet {
 199     public:
 200       resultSet (connection &amp;c, const query &amp;q);
 201       ~resultSet ();
 202       const char *option (const char *key) const;
 203       const char *option (const char *key, const char *val);
 204       size_t size () const;
 205       const record *getRecord (size_t i) const;
 206     };
 207    </screen>
 208   </para>
 209   <para>
 210    ### discusson
 211   </para>
 212  </sect1>
 213
 214  <sect1>
 215   <title><literal>ZOOM::record</literal></title>
 216   <para>
 217    SEE ALSO
 218    <ulink url="http://staging.zoom.z3950.org/api/zoom-1.3.html#3.5"
 219         >Section 3.5 (Record) of the ZOOM Abstract API</ulink>
 220   </para>
 221   <para>
 222    A <literal>ZOOM::record</literal> object represents a chunk of data
 223    from a <literal>resultSet</literal> returned from a server.
 224   </para>
 225   <para>
 226    The class has this declaration:
 227    <screen>
 228     class record {
 229     public:
 230       ~record ();
 231       enum syntax {
 232         UNKNOWN, GRS1, SUTRS, USMARC, UKMARC, XML
 233       };
 234       record *clone () const;
 235       syntax recsyn () const;
 236       const char *render () const;
 237       const char *rawdata () const;
 238     };
 239    </screen>
 240   </para>
 241   <para>
 242    ### discusson
 243   </para>
 244  </sect1>
 245
 246  <sect1>
 247   <title><literal>ZOOM::exception</literal> and subclasses</title>
 248   <para>
 249    SEE ALSO
 250    <ulink url="http://staging.zoom.z3950.org/api/zoom-1.3.html#3.7"
 251         >Section 3.7 (Exception) of the ZOOM Abstract API</ulink>
 252   </para>
 253   <para>
 254    The <literal>ZOOM::exception</literal> class is a virtual base
 255    class, representing a diagnostic generated by the ZOOM-C++ library
 256    or returned from a server.  ###
 257    <screen>
 258     class exception {
 259     public:
 260       exception (int code);
 261       int errcode () const;
 262       const char *errmsg () const;
 263     };
 264    </screen>
 265    This class has three (so far) concrete subclasses:
 266   </para>
 267
 268   <sect2>
 269    <title><literal>ZOOM::systemException</literal></title>
 270    <para>
 271     The class has this declaration:
 272     <screen>
 273     class systemException: public exception {
 274     public:
 275       systemException ();
 276       int errcode () const;
 277       const char *errmsg () const;
 278     };
 279     </screen>
 280    </para>
 281   </sect2>
 282
 283   <sect2>
 284    <title><literal>ZOOM::bib1Exception</literal></title>
 285    <para>
 286     The class has this declaration:
 287     <screen>
 288     class bib1Exception: public exception {
 289     public:
 290       bib1Exception (int errcode, const char *addinfo);
 291       int errcode () const;
 292       const char *errmsg () const;
 293       const char *addinfo () const;
 294     };
 295     </screen>
 296    </para>
 297   </sect2>
 298
 299   <sect2>
 300    <title><literal>ZOOM::queryException</literal></title>
 301    <para>
 302     The class has this declaration:
 303     <screen>
 304     class queryException: public exception {
 305     public:
 306       static const int PREFIX = 1;
 307       static const int CCL = 2;
 308       queryException (int qtype, const char *source);
 309       int errcode () const;
 310       const char *errmsg () const;
 311       const char *addinfo () const;
 312     };
 313     </screen>
 314    </para>
 315   </sect2>
 316
 317   <sect2>
 318    <title>Discussion</title>
 319    <para>
 320     ### discusson
 321    </para>
 322   </sect2>
 323  </sect1>
 324
 325 </chapter>
 326
 327  <!-- Keep this comment at the end of the file
 328  Local variables:
 329  mode: sgml
 330  sgml-omittag:t
 331  sgml-shorttag:t
 332  sgml-minimize-attributes:nil
 333  sgml-always-quote-attributes:t
 334  sgml-indent-step:1
 335  sgml-indent-data:t
 336  sgml-parent-document: "zebra.xml"
 337  sgml-local-catalogs: nil
 338  sgml-namecase-general:t
 339  End:
 340  -->