X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fzoom.xml;h=0d3fcab5f94e22ef552d439935b01d12c8d92eb3;hb=a598aaefa1dd2fb94b12cd367770345508a2740c;hp=709a2952f6d66a32b96d643e785ac45e40dd5124;hpb=b8248fc2b2eb866a23a677135deb4633cb1f3322;p=yazpp-moved-to-github.git diff --git a/doc/zoom.xml b/doc/zoom.xml index 709a295..0d3fcab 100644 --- a/doc/zoom.xml +++ b/doc/zoom.xml @@ -1,8 +1,9 @@ - + ZOOM-C++ - + + Introduction ZOOM @@ -27,7 +28,8 @@ The Complete Dinosaur from the Library of Congress's Z39.50 server: - + + #include <iostream> #include <yaz++/zoom.h> @@ -41,7 +43,8 @@ const record *rec = rs.getRecord(0); cout << rec->render() << endl; } - + + (Note that, for the sake of simplicity, this does not check for errors: we show a more realistic version of this program later.) @@ -96,21 +99,18 @@ - + + <literal>ZOOM::connection</literal> - SEE ALSO - Section 3.2 (Connection) of the ZOOM Abstract API - - A ZOOM::connection object represents an open connection to a Z39.50 server. Such a connection is forged by constructing a connection object. The class has this declaration: - + + class connection { public: connection (const char *hostname, int portnum); @@ -118,37 +118,77 @@ const char *option (const char *key) const; const char *option (const char *key, const char *val); }; - + + + When a new connection is created, the hostname + and port number of a Z39.50 server must be supplied, and the + network connection is forged and wrapped in the new object. If the + connection can't be established - perhaps because the hostname + couldn't be resolved, or there is no server listening on the + specified port - then an + exception + is thrown. - ### discusson + The only other methods on a connection object + are for getting and setting options. Any name-value pair of + strings may be set as options, and subsequently retrieved, but + certain options have special meanings which are understood by the + ZOOM code and affect the behaviour of the object that carries + them. For example, the value of the + databaseName option is used as the name of the + database to query when a search is executed against the + connection. For a full list of such special + options, see the ZOOM abstract API and the ZOOM-C documentation + (links below). + + + References + + + + Section 3.2 (Connection) of the ZOOM Abstract API + + + + + The Connections section of the ZOOM-C documentation + + + + - + + <literal>ZOOM::query</literal> and subclasses - SEE ALSO - Section 3.3 (Query) of the ZOOM Abstract API - - The ZOOM::query class is a virtual base class, representing a query to be submitted to a server. This class has - no methods, but two (so far) concrete subclasses: + no methods, but two (so far) concrete subclasses, each implementing + a specific query notation. <literal>ZOOM::prefixQuery</literal> The class has this declaration: - + + class prefixQuery : public query { public: prefixQuery (const char *pqn); ~prefixQuery (); }; - + + + It enables a query to be created from Yaz's cryptic but + powerful + Prefix Query Notation (PQN). @@ -156,13 +196,22 @@ <literal>ZOOM::CCLQuery</literal> The class has this declaration: - + + class CCLQuery : public query { public: CCLQuery (const char *ccl, void *qualset); ~CCLQuery (); }; - + + + It enables a query to be created using the simpler but less + expressive + Common Command Language (CCL). + The qualifiers recognised by the CCL parser are specified in an + external configuration file in the format described by the Yaz + documentation. @@ -175,26 +224,59 @@ resultSet class's constructor. - ### discusson + Given a suitable set of CCL qualifiers, the following pairs of + queries are equivalent: + + prefixQuery("dinosaur"); + CCLQuery("dinosaur"); + + prefixQuery("@and complete dinosaur"); + CCLQuery("complete and dinosaur"); + + prefixQuery("@and complete @or dinosaur pterosaur"); + CCLQuery("complete and (dinosaur or pterosaur)"); + + prefixQuery("@attr 1=7 0253333490"); + CCLQuery("isbn=0253333490"); + + + + + References + + + + Section 3.3 (Query) of the ZOOM Abstract API + + + + + The Queries section of the ZOOM-C documentation + + + - + + <literal>ZOOM::resultSet</literal> - SEE ALSO - Section 3.4 (Result Set) of the ZOOM Abstract API - - A ZOOM::resultSet object represents a set of - record identified by a query that has been executed against a - particular connection. + records identified by a query that has been executed against a + particular connection. The sole purpose of both + connection and query objects + is that they can be used to create new + resultSets - that is, to perform a search on the + server on the remote end of the connection. The class has this declaration: - + + class resultSet { public: resultSet (connection &c, const query &q); @@ -204,27 +286,71 @@ size_t size () const; const record *getRecord (size_t i) const; }; - + + + New resultSets are created by the constructor, + which is passed a connection, indicating the + server on which the search is to be performed, and a + query, indicating what search to perform. If + the search fails - for example, because the query is malformed - + then an + exception + is thrown. - ### discusson + Like connections, resultSet + objects can carry name-value options. The special options which + affect ZOOM-C++'s behaviour are the same as those for ZOOM-C and + are described in its documentation (link below). In particular, + the preferredRecordSyntax option may be set to + a string such as ``USMARC'', ``SUTRS'' etc. to indicate what the + format in which records should be retrieved; and the + elementSetName option indicates whether brief + records (``B''), full records (``F'') or some other composition + should be used. + + The size() method returns the number of records + in the result set. Zero is a legitimate value: a search that finds + no records is not the same as a search that fails. + + + Finally, the getRecord method returns the + ith record from the result set, where + i is zero-based: that is, legitmate values + range from zero up to one less than the result-set size. + + + + References + + + + Section 3.4 (Result Set) of the ZOOM Abstract API + + + + + The Result Sets section of the ZOOM-C documentation + + + + - + + <literal>ZOOM::record</literal> - SEE ALSO - Section 3.5 (Record) of the ZOOM Abstract API - - A ZOOM::record object represents a chunk of data from a resultSet returned from a server. The class has this declaration: - + + class record { public: ~record (); @@ -236,32 +362,47 @@ const char *render () const; const char *rawdata () const; }; - - + ### discusson + + + References + + + + Section 3.5 (Record) of the ZOOM Abstract API + + + + + The Records section of the ZOOM-C documentation + + + + - + + <literal>ZOOM::exception</literal> and subclasses - SEE ALSO - Section 3.7 (Exception) of the ZOOM Abstract API - - The ZOOM::exception class is a virtual base class, representing a diagnostic generated by the ZOOM-C++ library or returned from a server. ### - + + class exception { public: exception (int code); int errcode () const; const char *errmsg () const; }; - + + This class has three (so far) concrete subclasses: @@ -269,22 +410,23 @@ <literal>ZOOM::systemException</literal> The class has this declaration: - + + class systemException: public exception { public: systemException (); int errcode () const; const char *errmsg () const; }; - - + <literal>ZOOM::bib1Exception</literal> The class has this declaration: - + + class bib1Exception: public exception { public: bib1Exception (int errcode, const char *addinfo); @@ -292,15 +434,15 @@ const char *errmsg () const; const char *addinfo () const; }; - - + <literal>ZOOM::queryException</literal> The class has this declaration: - + + class queryException: public exception { public: static const int PREFIX = 1; @@ -310,8 +452,7 @@ const char *errmsg () const; const char *addinfo () const; }; - - + @@ -320,6 +461,27 @@ ### discusson + + + References + + + + Section 3.7 (Exception) of the ZOOM Abstract API + + + + + Because C does not support exceptions, ZOOM-C has no API element + that corresponds directly with ZOOM-C++'s + exception class and its subclasses. The + closest thing is the ZOOM_connection_error + function described in + The Connections section of the documentation. + +