2 <!-- $Id: zoom.xml,v 1.5 2002-10-09 23:11:31 mike Exp $ -->
3 <title>ZOOM-C++</title>
6 <sect1 id="zoom-introduction">
7 <title>Introduction</title>
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.
20 The Yaz++ library includes an implementation of the <ulink
21 url="http://staging.zoom.z3950.org/bind/cplusplus/"
23 for ZOOM, enabling quick, easy development of client applications.
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:
33 #include <iostream>
34 #include <yaz++/zoom.h>
38 int main(int argc, char **argv)
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 << rec->render() << endl;
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.)
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"/>
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:
66 <literal>connection</literal>
72 <literal>query</literal> and its subclasses
73 <literal>prefixQuery</literal> and
74 <literal>CCLQuery</literal>
80 <literal>resultSet</literal>
86 <literal>record</literal>
92 <literal>exception</literal> and its subclasses
93 <literal>systemException</literal>,
94 <literal>bib1Exception</literal> and
95 <literal>queryException</literal>
103 <sect1 id="zoom-connection">
104 <title><literal>ZOOM::connection</literal></title>
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.
111 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);
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>
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
147 <title>References</title>
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>
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>
166 <sect1 id="zoom-query">
167 <title><literal>ZOOM::query</literal> and subclasses</title>
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.
176 <title><literal>ZOOM::prefixQuery</literal></title>
178 The class has this declaration:
181 class prefixQuery : public query {
183 prefixQuery (const char *pqn);
188 It enables a query to be created from Yaz's cryptic but
190 <ulink url="file:///usr/local/src/z39.50/yaz/doc/tools.html#PQF"
191 >Prefix Query Notation (PQN)</ulink>.
196 <title><literal>ZOOM::CCLQuery</literal></title>
198 The class has this declaration:
201 class CCLQuery : public query {
203 CCLQuery (const char *ccl, void *qualset);
208 It enables a query to be created using the simpler but less
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
219 <title>Discussion</title>
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.
227 Given a suitable set of CCL qualifiers, the following pairs of
228 queries are equivalent:
231 prefixQuery("dinosaur");
232 CCLQuery("dinosaur");
234 prefixQuery("@and complete dinosaur");
235 CCLQuery("complete and dinosaur");
237 prefixQuery("@and complete @or dinosaur pterosaur");
238 CCLQuery("complete and (dinosaur or pterosaur)");
240 prefixQuery("@attr 1=7 0253333490");
241 CCLQuery("isbn=0253333490");
246 <title>References</title>
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>
256 <ulink url="file:///usr/local/src/z39.50/yaz/doc/zoom.query.html"
257 >The Queries section of the ZOOM-C documentation</ulink>
265 <sect1 id="zoom-resultset">
266 <title><literal>ZOOM::resultSet</literal></title>
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.
277 The class has this declaration:
282 resultSet (connection &c, const query &q);
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;
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 -
297 <link linkend="zoom-exception"><literal>exception</literal></link>
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
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.
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.
325 <title>References</title>
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>
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>
344 <sect1 id="zoom-record">
345 <title><literal>ZOOM::record</literal></title>
347 A <literal>ZOOM::record</literal> object represents a chunk of data
348 from a <literal>resultSet</literal> returned from a server.
351 The class has this declaration:
358 UNKNOWN, GRS1, SUTRS, USMARC, UKMARC, XML
360 record *clone () const;
361 syntax recsyn () const;
362 const char *render () const;
363 const char *rawdata () const;
371 <title>References</title>
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>
381 <ulink url="file:///usr/local/src/z39.50/yaz/doc/zoom.records.html"
382 >The Records section of the ZOOM-C documentation</ulink>
390 <sect1 id="zoom-exception">
391 <title><literal>ZOOM::exception</literal> and subclasses</title>
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. ###
400 exception (int code);
401 int errcode () const;
402 const char *errmsg () const;
406 This class has three (so far) concrete subclasses:
410 <title><literal>ZOOM::systemException</literal></title>
412 The class has this declaration:
415 class systemException: public exception {
418 int errcode () const;
419 const char *errmsg () const;
425 <title><literal>ZOOM::bib1Exception</literal></title>
427 The class has this declaration:
430 class bib1Exception: public exception {
432 bib1Exception (int errcode, const char *addinfo);
433 int errcode () const;
434 const char *errmsg () const;
435 const char *addinfo () const;
441 <title><literal>ZOOM::queryException</literal></title>
443 The class has this declaration:
446 class queryException: public exception {
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;
459 <title>Discussion</title>
466 <title>References</title>
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>
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.
489 <!-- Keep this comment at the end of the file
494 sgml-minimize-attributes:nil
495 sgml-always-quote-attributes:t
498 sgml-parent-document: "zebra.xml"
499 sgml-local-catalogs: nil
500 sgml-namecase-general:t