doc/zoom.xml

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