From 096af05205c65b89240855fc35ad3e898050d5e4 Mon Sep 17 00:00:00 2001 From: Mike Taylor Date: Wed, 9 Oct 2002 23:11:31 +0000 Subject: [PATCH] Work on zoom.xml --- doc/zoom.xml | 234 ++++++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 196 insertions(+), 38 deletions(-) diff --git a/doc/zoom.xml b/doc/zoom.xml index 7aac7d8..0d3fcab 100644 --- a/doc/zoom.xml +++ b/doc/zoom.xml @@ -1,8 +1,9 @@ - + ZOOM-C++ - + + Introduction ZOOM @@ -98,14 +99,10 @@ - + + <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. @@ -123,21 +120,56 @@ }; - ### discusson + 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. + + + 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. @@ -152,6 +184,12 @@ ~prefixQuery (); }; + + It enables a query to be created from Yaz's cryptic but + powerful + Prefix Query Notation (PQN). + @@ -166,6 +204,15 @@ ~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. + @@ -177,22 +224,54 @@ 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: @@ -209,18 +288,62 @@ }; - ### discusson + 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. + + 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. @@ -243,16 +366,30 @@ ### 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. ### @@ -324,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. + + -- 1.7.10.4