2 <!-- $Id: zoom.xml,v 1.4 2002-10-09 11:44:44 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:
32 #include <iostream>
33 #include <yaz++/zoom.h>
37 int main(int argc, char **argv)
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 << rec->render() << endl;
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.)
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"/>
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:
65 <literal>connection</literal>
71 <literal>query</literal> and its subclasses
72 <literal>prefixQuery</literal> and
73 <literal>CCLQuery</literal>
79 <literal>resultSet</literal>
85 <literal>record</literal>
91 <literal>exception</literal> and its subclasses
92 <literal>systemException</literal>,
93 <literal>bib1Exception</literal> and
94 <literal>queryException</literal>
102 <title><literal>ZOOM::connection</literal></title>
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>
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.
114 The class has this declaration:
119 connection (const char *hostname, int portnum);
121 const char *option (const char *key) const;
122 const char *option (const char *key, const char *val);
131 <title><literal>ZOOM::query</literal> and subclasses</title>
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>
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:
144 <title><literal>ZOOM::prefixQuery</literal></title>
146 The class has this declaration:
149 class prefixQuery : public query {
151 prefixQuery (const char *pqn);
158 <title><literal>ZOOM::CCLQuery</literal></title>
160 The class has this declaration:
163 class CCLQuery : public query {
165 CCLQuery (const char *ccl, void *qualset);
172 <title>Discussion</title>
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.
186 <title><literal>ZOOM::resultSet</literal></title>
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>
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.
198 The class has this declaration:
203 resultSet (connection &c, const query &q);
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;
217 <title><literal>ZOOM::record</literal></title>
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>
224 A <literal>ZOOM::record</literal> object represents a chunk of data
225 from a <literal>resultSet</literal> returned from a server.
228 The class has this declaration:
235 UNKNOWN, GRS1, SUTRS, USMARC, UKMARC, XML
237 record *clone () const;
238 syntax recsyn () const;
239 const char *render () const;
240 const char *rawdata () const;
249 <title><literal>ZOOM::exception</literal> and subclasses</title>
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>
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. ###
263 exception (int code);
264 int errcode () const;
265 const char *errmsg () const;
269 This class has three (so far) concrete subclasses:
273 <title><literal>ZOOM::systemException</literal></title>
275 The class has this declaration:
278 class systemException: public exception {
281 int errcode () const;
282 const char *errmsg () const;
288 <title><literal>ZOOM::bib1Exception</literal></title>
290 The class has this declaration:
293 class bib1Exception: public exception {
295 bib1Exception (int errcode, const char *addinfo);
296 int errcode () const;
297 const char *errmsg () const;
298 const char *addinfo () const;
304 <title><literal>ZOOM::queryException</literal></title>
306 The class has this declaration:
309 class queryException: public exception {
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;
322 <title>Discussion</title>
331 <!-- Keep this comment at the end of the file
336 sgml-minimize-attributes:nil
337 sgml-always-quote-attributes:t
340 sgml-parent-document: "zebra.xml"
341 sgml-local-catalogs: nil
342 sgml-namecase-general:t