doc/zoom.xml

   1 <chapter id="zoom">
   2  <!-- $Id: zoom.xml,v 1.5 2002-10-09 23:11:31 mike Exp $ -->
   3  <title>ZOOM-C++</title>
   4
   5
   6  <sect1 id="zoom-introduction">
   7   <title>Introduction</title>
   8   <para>
   9    <ulink url="http://staging.zoom.z3950.org/">ZOOM</ulink>
  10    is the emerging standard API for information retrieval programming
  11    using the Z39.50 protocol.  ZOOM's
  12    <ulink url="http://staging.zoom.z3950.org/api/">Abstract API</ulink>
  13    specifies semantics for classes representing key IR concepts such as
  14    connections, queries, result sets and records; and there are various
  15    <ulink url="http://staging.zoom.z3950.org/bind/">bindings</ulink>
  16    specifying how those concepts should be represented in various
  17    programming languages.
  18   </para>
  19   <para>
  20    The Yaz++ library includes an implementation of the <ulink
  21    url="http://staging.zoom.z3950.org/bind/cplusplus/"
  22         >C++ binding</ulink>
  23    for ZOOM, enabling quick, easy development of client applications.
  24   </para>
  25   <para>
  26    For example, here is a tiny Z39.50 client that fetches and displays
  27    the MARC record for Farlow & Brett Surman's
  28    <!-- ### there must be a better way to mark up a book title? -->
  29    <emphasis>The Complete Dinosaur</emphasis>
  30    from the Library of Congress's Z39.50 server:
  31   </para>
  32   <synopsis>
  33     #include &lt;iostream&gt;
  34     #include &lt;yaz++/zoom.h&gt;
  35
  36     using namespace ZOOM;
  37
  38     int main(int argc, char **argv)
  39     {
  40         connection conn("z3950.loc.gov", 7090);
  41         conn.option("databaseName", "Voyager");
  42         resultSet rs(conn, prefixQuery("@attr attr 1=7 0253333490"));
  43         const record *rec = rs.getRecord(0);
  44         cout &lt;&lt; rec-&gt;render() &lt;&lt; endl;
  45     }
  46   </synopsis>
  47   <para>
  48    (Note that, for the sake of simplicity, this does not check for
  49    errors: we show a more realistic version of this program later.)
  50   </para>
  51   <para>
  52    Yaz++'s implementation of the C++ binding is a thin layer over Yaz's
  53    implementation of the C binding.  For information on the supported
  54    options and other such details, see the ZOOM-C documentation, which
  55    can be found on-line at
  56    <ulink url="http://www.indexdata.dk/yaz/doc/zoom.php"/>
  57   </para>
  58   <para>
  59    All of the classes defined by ZOOM-C++ are in the
  60    <literal>ZOOM</literal> namespace.  We will now consider
  61    the five main classes in turn:
  62
  63    <itemizedlist>
  64     <listitem>
  65      <para>
  66       <literal>connection</literal>
  67      </para>
  68     </listitem>
  69
  70     <listitem>
  71      <para>
  72       <literal>query</literal> and its subclasses
  73       <literal>prefixQuery</literal> and
  74       <literal>CCLQuery</literal>
  75      </para>
  76     </listitem>
  77
  78     <listitem>
  79      <para>
  80       <literal>resultSet</literal>
  81      </para>
  82     </listitem>
  83
  84     <listitem>
  85      <para>
  86       <literal>record</literal>
  87      </para>
  88     </listitem>
  89
  90     <listitem>
  91      <para>
  92       <literal>exception</literal> and its subclasses
  93       <literal>systemException</literal>,
  94       <literal>bib1Exception</literal> and
  95       <literal>queryException</literal>
  96      </para>
  97     </listitem>
  98    </itemizedlist>
  99   </para>
 100  </sect1>
 101
 102
 103  <sect1 id="zoom-connection">
 104   <title><literal>ZOOM::connection</literal></title>
 105   <para>
 106    A <literal>ZOOM::connection</literal> object represents an open
 107    connection to a Z39.50 server.  Such a connection is forged by
 108    constructing a <literal>connection</literal> object.
 109   </para>
 110   <para>
 111    The class has this declaration:
 112   </para>
 113   <synopsis>
 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   </synopsis>
 122   <para>
 123    When a new <literal>connection</literal> is created, the hostname
 124    and port number of a Z39.50 server must be supplied, and the
 125    network connection is forged and wrapped in the new object.  If the
 126    connection can't be established - perhaps because the hostname
 127    couldn't be resolved, or there is no server listening on the
 128    specified port - then an
 129    <link linkend="zoom-exception"><literal>exception</literal></link>
 130    is thrown.
 131   </para>
 132   <para>
 133    The only other methods on a <literal>connection</literal> object
 134    are for getting and setting options.  Any name-value pair of
 135    strings may be set as options, and subsequently retrieved, but
 136    certain options have special meanings which are understood by the
 137    ZOOM code and affect the behaviour of the object that carries
 138    them.  For example, the value of the
 139    <literal>databaseName</literal> option is used as the name of the
 140    database to query when a search is executed against the
 141    <literal>connection</literal>.  For a full list of such special
 142    options, see the ZOOM abstract API and the ZOOM-C documentation
 143    (links below).
 144   </para>
 145
 146   <sect2>
 147    <title>References</title>
 148    <itemizedlist>
 149     <listitem>
 150      <para>
 151       <ulink url="http://staging.zoom.z3950.org/api/zoom-1.3.html#3.2"
 152         >Section 3.2 (Connection) of the ZOOM Abstract API</ulink>
 153      </para>
 154     </listitem>
 155     <listitem>
 156      <para>
 157       <ulink url="file:///usr/local/src/z39.50/yaz/doc/zoom.html#zoom.connections"
 158         >The Connections section of the ZOOM-C documentation</ulink>
 159      </para>
 160     </listitem>
 161    </itemizedlist>
 162   </sect2>
 163  </sect1>
 164
 165
 166  <sect1 id="zoom-query">
 167   <title><literal>ZOOM::query</literal> and subclasses</title>
 168   <para>
 169    The <literal>ZOOM::query</literal> class is a virtual base class,
 170    representing a query to be submitted to a server.  This class has
 171    no methods, but two (so far) concrete subclasses, each implementing
 172    a specific query notation.
 173   </para>
 174
 175   <sect2>
 176    <title><literal>ZOOM::prefixQuery</literal></title>
 177    <para>
 178     The class has this declaration:
 179    </para>
 180    <synopsis>
 181     class prefixQuery : public query {
 182     public:
 183       prefixQuery (const char *pqn);
 184       ~prefixQuery ();
 185     };
 186    </synopsis>
 187    <para>
 188     It enables a query to be created from Yaz's cryptic but
 189     powerful
 190     <ulink url="file:///usr/local/src/z39.50/yaz/doc/tools.html#PQF"
 191         >Prefix Query Notation (PQN)</ulink>.
 192    </para>
 193   </sect2>
 194
 195   <sect2>
 196    <title><literal>ZOOM::CCLQuery</literal></title>
 197    <para>
 198     The class has this declaration:
 199    </para>
 200    <synopsis>
 201     class CCLQuery : public query {
 202     public:
 203       CCLQuery (const char *ccl, void *qualset);
 204       ~CCLQuery ();
 205     };
 206    </synopsis>
 207    <para>
 208     It enables a query to be created using the simpler but less
 209     expressive
 210     <ulink url="file:///usr/local/src/z39.50/yaz/doc/tools.html#CCL"
 211         >Common Command Language (CCL)</ulink>.
 212     The qualifiers recognised by the CCL parser are specified in an
 213     external configuration file in the format described by the Yaz
 214     documentation.
 215    </para>
 216   </sect2>
 217
 218   <sect2>
 219    <title>Discussion</title>
 220    <para>
 221     It will be readily recognised that these objects have no methods
 222     other than their constructors: their only role in life is to be
 223     used in searching, by being passed to the
 224     <literal>resultSet</literal> class's constructor.
 225    </para>
 226    <para>
 227     Given a suitable set of CCL qualifiers, the following pairs of
 228     queries are equivalent:
 229    </para>
 230    <screen>
 231     prefixQuery("dinosaur");
 232     CCLQuery("dinosaur");
 233
 234     prefixQuery("@and complete dinosaur");
 235     CCLQuery("complete and dinosaur");
 236
 237     prefixQuery("@and complete @or dinosaur pterosaur");
 238     CCLQuery("complete and (dinosaur or pterosaur)");
 239
 240     prefixQuery("@attr 1=7 0253333490");
 241     CCLQuery("isbn=0253333490");
 242    </screen>
 243   </sect2>
 244
 245   <sect2>
 246    <title>References</title>
 247    <itemizedlist>
 248     <listitem>
 249      <para>
 250       <ulink url="http://staging.zoom.z3950.org/api/zoom-1.3.html#3.3"
 251         >Section 3.3 (Query) of the ZOOM Abstract API</ulink>
 252      </para>
 253     </listitem>
 254     <listitem>
 255      <para>
 256       <ulink url="file:///usr/local/src/z39.50/yaz/doc/zoom.query.html"
 257         >The Queries section of the ZOOM-C documentation</ulink>
 258      </para>
 259     </listitem>
 260    </itemizedlist>
 261   </sect2>
 262  </sect1>
 263
 264
 265  <sect1 id="zoom-resultset">
 266   <title><literal>ZOOM::resultSet</literal></title>
 267   <para>
 268    A <literal>ZOOM::resultSet</literal> object represents a set of
 269    records identified by a query that has been executed against a
 270    particular connection.  The sole purpose of both
 271    <literal>connection</literal> and <literal>query</literal> objects
 272    is that they can be used to create new
 273    <literal>resultSet</literal>s - that is, to perform a search on the
 274    server on the remote end of the connection.
 275   </para>
 276   <para>
 277    The class has this declaration:
 278   </para>
 279   <synopsis>
 280     class resultSet {
 281     public:
 282       resultSet (connection &amp;c, const query &amp;q);
 283       ~resultSet ();
 284       const char *option (const char *key) const;
 285       const char *option (const char *key, const char *val);
 286       size_t size () const;
 287       const record *getRecord (size_t i) const;
 288     };
 289   </synopsis>
 290   <para>
 291    New <literal>resultSet</literal>s are created by the constructor,
 292    which is passed a <literal>connection</literal>, indicating the
 293    server on which the search is to be performed, and a
 294    <literal>query</literal>, indicating what search to perform.  If
 295    the search fails - for example, because the query is malformed -
 296    then an
 297    <link linkend="zoom-exception"><literal>exception</literal></link>
 298    is thrown.
 299   </para>
 300   <para>
 301    Like <literal>connection</literal>s, <literal>resultSet</literal>
 302    objects can carry name-value options.  The special options which
 303    affect ZOOM-C++'s behaviour are the same as those for ZOOM-C and
 304    are described in its documentation (link below).  In particular,
 305    the <literal>preferredRecordSyntax</literal> option may be set to
 306    a string such as ``USMARC'', ``SUTRS'' etc. to indicate what the
 307    format in which records should be retrieved; and the
 308    <literal>elementSetName</literal> option indicates whether brief
 309    records (``B''), full records (``F'') or some other composition
 310    should be used.
 311   </para>
 312   <para>
 313    The <literal>size()</literal> method returns the number of records
 314    in the result set.  Zero is a legitimate value: a search that finds
 315    no records is not the same as a search that fails.
 316   </para>
 317   <para>
 318    Finally, the <literal>getRecord</literal> method returns the
 319    <parameter>i</parameter>th record from the result set, where
 320    <parameter>i</parameter> is zero-based: that is, legitmate values
 321    range from zero up to one less than the result-set size.
 322   </para>
 323
 324   <sect2>
 325    <title>References</title>
 326    <itemizedlist>
 327     <listitem>
 328      <para>
 329       <ulink url="http://staging.zoom.z3950.org/api/zoom-1.3.html#3.4"
 330         >Section 3.4 (Result Set) of the ZOOM Abstract API</ulink>
 331      </para>
 332     </listitem>
 333     <listitem>
 334      <para>
 335       <ulink url="file:///usr/local/src/z39.50/yaz/doc/zoom.resultsets.html"
 336         >The Result Sets section of the ZOOM-C documentation</ulink>
 337      </para>
 338     </listitem>
 339    </itemizedlist>
 340   </sect2>
 341  </sect1>
 342
 343
 344  <sect1 id="zoom-record">
 345   <title><literal>ZOOM::record</literal></title>
 346   <para>
 347    A <literal>ZOOM::record</literal> object represents a chunk of data
 348    from a <literal>resultSet</literal> returned from a server.
 349   </para>
 350   <para>
 351    The class has this declaration:
 352   </para>
 353   <synopsis>
 354     class record {
 355     public:
 356       ~record ();
 357       enum syntax {
 358         UNKNOWN, GRS1, SUTRS, USMARC, UKMARC, XML
 359       };
 360       record *clone () const;
 361       syntax recsyn () const;
 362       const char *render () const;
 363       const char *rawdata () const;
 364     };
 365   </synopsis>
 366   <para>
 367    ### discusson
 368   </para>
 369
 370   <sect2>
 371    <title>References</title>
 372    <itemizedlist>
 373     <listitem>
 374      <para>
 375       <ulink url="http://staging.zoom.z3950.org/api/zoom-1.3.html#3.5"
 376         >Section 3.5 (Record) of the ZOOM Abstract API</ulink>
 377      </para>
 378     </listitem>
 379     <listitem>
 380      <para>
 381       <ulink url="file:///usr/local/src/z39.50/yaz/doc/zoom.records.html"
 382         >The Records section of the ZOOM-C documentation</ulink>
 383      </para>
 384     </listitem>
 385    </itemizedlist>
 386   </sect2>
 387  </sect1>
 388
 389
 390  <sect1 id="zoom-exception">
 391   <title><literal>ZOOM::exception</literal> and subclasses</title>
 392   <para>
 393    The <literal>ZOOM::exception</literal> class is a virtual base
 394    class, representing a diagnostic generated by the ZOOM-C++ library
 395    or returned from a server.  ###
 396   </para>
 397   <synopsis>
 398     class exception {
 399     public:
 400       exception (int code);
 401       int errcode () const;
 402       const char *errmsg () const;
 403     };
 404   </synopsis>
 405   <para>
 406    This class has three (so far) concrete subclasses:
 407   </para>
 408
 409   <sect2>
 410    <title><literal>ZOOM::systemException</literal></title>
 411    <para>
 412     The class has this declaration:
 413    </para>
 414    <synopsis>
 415     class systemException: public exception {
 416     public:
 417       systemException ();
 418       int errcode () const;
 419       const char *errmsg () const;
 420     };
 421    </synopsis>
 422   </sect2>
 423
 424   <sect2>
 425    <title><literal>ZOOM::bib1Exception</literal></title>
 426    <para>
 427     The class has this declaration:
 428    </para>
 429    <synopsis>
 430     class bib1Exception: public exception {
 431     public:
 432       bib1Exception (int errcode, const char *addinfo);
 433       int errcode () const;
 434       const char *errmsg () const;
 435       const char *addinfo () const;
 436     };
 437    </synopsis>
 438   </sect2>
 439
 440   <sect2>
 441    <title><literal>ZOOM::queryException</literal></title>
 442    <para>
 443     The class has this declaration:
 444    </para>
 445    <synopsis>
 446     class queryException: public exception {
 447     public:
 448       static const int PREFIX = 1;
 449       static const int CCL = 2;
 450       queryException (int qtype, const char *source);
 451       int errcode () const;
 452       const char *errmsg () const;
 453       const char *addinfo () const;
 454     };
 455    </synopsis>
 456   </sect2>
 457
 458   <sect2>
 459    <title>Discussion</title>
 460    <para>
 461     ### discusson
 462    </para>
 463   </sect2>
 464
 465   <sect2>
 466    <title>References</title>
 467    <itemizedlist>
 468     <listitem>
 469      <para>
 470       <ulink url="http://staging.zoom.z3950.org/api/zoom-1.3.html#3.7"
 471         >Section 3.7 (Exception) of the ZOOM Abstract API</ulink>
 472      </para>
 473     </listitem>
 474    </itemizedlist>
 475    <para>
 476     Because C does not support exceptions, ZOOM-C has no API element
 477     that corresponds directly with ZOOM-C++'s
 478     <literal>exception</literal> class and its subclasses.  The
 479     closest thing is the <literal>ZOOM_connection_error</literal>
 480     function described in
 481     <ulink url="file:///usr/local/src/z39.50/yaz/doc/zoom.html#zoom.connections"
 482         >The Connections section</ulink> of the documentation.
 483    </para>
 484   </sect2>
 485  </sect1>
 486
 487 </chapter>
 488
 489  <!-- Keep this comment at the end of the file
 490  Local variables:
 491  mode: sgml
 492  sgml-omittag:t
 493  sgml-shorttag:t
 494  sgml-minimize-attributes:nil
 495  sgml-always-quote-attributes:t
 496  sgml-indent-step:1
 497  sgml-indent-data:t
 498  sgml-parent-document: "zebra.xml"
 499  sgml-local-catalogs: nil
 500  sgml-namecase-general:t
 501  End:
 502  -->