2 <!-- $Id: zoom.xml,v 1.3 2002-10-09 09:07:10 mike Exp $ -->
3 <title>ZOOM-C++</title>
5 <sect1 id="zoom.introduction">
6 <title>Introduction</title>
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.
19 The Yaz++ library includes an implementation of the <ulink
20 url="http://staging.zoom.z3950.org/bind/cplusplus/"
22 for ZOOM, enabling quick, easy development of client applications.
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:
31 #include <iostream>
32 #include <yaz++/zoom.h>
36 int main(int argc, char **argv)
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 << rec->render() << endl;
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.)
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"/>
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:
63 <literal>connection</literal>
69 <literal>query</literal> and its subclasses
70 <literal>prefixQuery</literal> and
71 <literal>CCLQuery</literal>
77 <literal>resultSet</literal>
83 <literal>record</literal>
89 <literal>exception</literal> and its subclasses
90 <literal>systemException</literal>,
91 <literal>bib1Exception</literal> and
92 <literal>queryException</literal>
100 <title><literal>ZOOM::connection</literal></title>
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>
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.
112 The class has this declaration:
116 connection (const char *hostname, int portnum);
118 const char *option (const char *key) const;
119 const char *option (const char *key, const char *val);
129 <title><literal>ZOOM::query</literal> and subclasses</title>
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>
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:
142 <title><literal>ZOOM::prefixQuery</literal></title>
144 The class has this declaration:
146 class prefixQuery : public query {
148 prefixQuery (const char *pqn);
156 <title><literal>ZOOM::CCLQuery</literal></title>
158 The class has this declaration:
160 class CCLQuery : public query {
162 CCLQuery (const char *ccl, void *qualset);
170 <title>Discussion</title>
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.
184 <title><literal>ZOOM::resultSet</literal></title>
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>
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.
196 The class has this declaration:
200 resultSet (connection &c, const query &q);
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;
215 <title><literal>ZOOM::record</literal></title>
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>
222 A <literal>ZOOM::record</literal> object represents a chunk of data
223 from a <literal>resultSet</literal> returned from a server.
226 The class has this declaration:
232 UNKNOWN, GRS1, SUTRS, USMARC, UKMARC, XML
234 record *clone () const;
235 syntax recsyn () const;
236 const char *render () const;
237 const char *rawdata () const;
247 <title><literal>ZOOM::exception</literal> and subclasses</title>
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>
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. ###
260 exception (int code);
261 int errcode () const;
262 const char *errmsg () const;
265 This class has three (so far) concrete subclasses:
269 <title><literal>ZOOM::systemException</literal></title>
271 The class has this declaration:
273 class systemException: public exception {
276 int errcode () const;
277 const char *errmsg () const;
284 <title><literal>ZOOM::bib1Exception</literal></title>
286 The class has this declaration:
288 class bib1Exception: public exception {
290 bib1Exception (int errcode, const char *addinfo);
291 int errcode () const;
292 const char *errmsg () const;
293 const char *addinfo () const;
300 <title><literal>ZOOM::queryException</literal></title>
302 The class has this declaration:
304 class queryException: public exception {
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;
318 <title>Discussion</title>
327 <!-- Keep this comment at the end of the file
332 sgml-minimize-attributes:nil
333 sgml-always-quote-attributes:t
336 sgml-parent-document: "zebra.xml"
337 sgml-local-catalogs: nil
338 sgml-namecase-general:t