+In general, method calls throw an exception if anything goes wrong, so
+you don't need to test for success after each call. See the section
+below on the Exception class for details.
+
+=head1 UTILITY FUNCTION
+
+=head2 ZOOM::diag_str()
+
+ $msg = ZOOM::diag_str(ZOOM::Error::INVALID_QUERY);
+
+Returns a human-readable English-language string corresponding to the
+error code that is its own parameter. This works for any error-code
+returned from
+C<ZOOM::Exception::code()>,
+C<ZOOM::Connection::error_x()>
+or
+C<ZOOM::Connection::errcode()>,
+irrespective of whether it is a member of the C<ZOOM::Error>
+enumeration or drawn from the BIB-1 diagnostic set.
+
+=head1 CLASSES
+
+The eight ZOOM classes are described here in ``sensible order'':
+first, the four commonly used classes, in the he order that they will
+tend to be used in most programs (Connection, ResultSet, Record,
+Exception); then the four more esoteric classes in descending order of
+how often they are needed.
+
+With the exception of the Options class, which is an extension to the
+ZOOM model, the introduction to each class includes a link to the
+relevant section of the ZOOM Abstract API.
+
+=head2 ZOOM::Connection
+
+ $conn = new ZOOM::Connection("indexdata.dk:210/gils");
+ print("server is '", $conn->option("serverImplementationName"), "'\n");
+ $conn->option(preferredRecordSyntax => "usmarc");
+ $conn->option_binary(iconBlob => "foo\0bar");
+ $rs = $conn->search_pqf('@attr 1=4 mineral');/usr/local/src/mike/records/acc-ounts/cheques-
+ $ss = $conn->scan('@attr 1=1003 a');
+ if ($conn->errcode() != 0) {
+ die("somthing went wrong: " . $conn->errmsg())
+ }
+ $conn->destroy()
+
+This class represents a connection to an information retrieval server,
+using an IR protocol such as ANSI/NISO Z39.50, SRW (the
+Search/Retrieve Webservice), SRU (the Search/Retrieve URL) or
+OpenSearch. Not all of these protocols require a low-level connection
+to be maintained, but the Connection object nevertheless provides a
+location for the necessary cache of configuration and state
+information, as well as a uniform API to the connection-oriented
+facilities (searching, index browsing, etc.), provided by these
+protocols.
+
+See the description of the C<Connection> class in the ZOOM Abstract
+API at
+http://zoom.z3950.org/api/zoom-current.html#3.2
+
+=head3 Methods
+
+=head4 new()
+
+ $conn = new ZOOM::Connection("indexdata.dk", 210);
+ $conn = new ZOOM::Connection("indexdata.dk:210/gils");
+ $conn = new ZOOM::Connection("tcp:indexdata.dk:210/gils");
+ $conn = new ZOOM::Connection("http:indexdata.dk:210/gils");
+
+Creates a new Connection object, and immediately connects it to the
+specified server. If you want to make a new Connection object but
+delay forging the connection, use the C<create()> and C<connect()>
+methods instead.
+
+This constructor can be called with two arguments or a single
+argument. In the former case, the arguments are the name and port
+number of the Z39.50 server to connect to; in the latter case, the
+single argument is a YAZ service-specifier string of the form
+
+=over 4
+
+=item
+
+[I<scheme>:]I<host>[:I<port>][/I<databaseName>]
+
+=back
+
+In which the I<host> and I<port> parts are as in the two-argument
+form, the I<databaseName> if provided specifies the name of the
+database to be used in subsequent searches on this connection, and the
+optional I<scheme> (default C<tcp>) indicates what protocol should be
+used. At present, the following schemes are supported:
+
+=over 4
+
+=item tcp
+
+Z39.50 connection.
+
+=item ssl
+
+Z39.50 connection encrypted using SSL (Secure Sockets Layer). Not
+many servers support this, but Index Data's Zebra is one that does.
+
+=item unix
+
+Z39.50 connection on a Unix-domain (local) socket, in which case the
+I<hostname> portion of the string is instead used as a filename in the
+local filesystem.
+
+=item http
+
+SRW connection using SOAP over HTTP.
+
+=back
+
+Support for SRU will follow in the fullness of time.
+
+=head4 create()
+
+=head4 connect()
+
+=head4 error_x() / errcode() / errmsg() / addinfo()
+
+=head4 option() / option_binary()
+
+=head4 search() / search_pqf()
+
+=head4 scan()
+
+=head4 package()
+
+=head4 destroy()
+
+=head2 ZOOM::ResultSet
+
+I<###>
+
+=head2 ZOOM::Record
+
+I<###>
+
+=head2 ZOOM::Exception
+
+In general, method calls throw an exception (of class
+C<ZOOM::Exception>) if anything goes wrong, so you don't need to test
+for success after each call. Exceptions are caught by enclosing the
+main code in an C<eval{}> block and checking C<$@> on exit from that
+block, as in the code-sample above.
+
+There are a small number of exceptions to this rule.
+I<###>
+
+=head2 ZOOM::ScanSet
+
+I<###>
+
+=head2 ZOOM::Package
+
+I<###>
+
+=head2 ZOOM::Query
+
+I<###>
+
+=head2 ZOOM::Options
+
+I<###>
+
+=head1 ENUMERATIONS
+
+The ZOOM module provides two enumerations that list possible return
+values from particular functions. They are described in the following
+sections.
+
+=head2 ZOOM::Error
+
+ if ($@->code() == ZOOM::Error::QUERY_PQF) {
+ return "your query was not accepted";
+ }
+
+This class provides a set of manifest constants representing some of
+the possible error codes that can be raised by the ZOOM module. The
+methods that return error-codes are
+C<ZOOM::Exception::code()>,
+C<ZOOM::Connection::error_x()>
+and
+C<ZOOM::Connection::errcode()>.
+
+The C<ZOOM::Error> class provides the constants
+C<NONE>,
+C<CONNECT>,
+C<MEMORY>,
+C<ENCODE>,
+C<DECODE>,
+C<CONNECTION_LOST>,
+C<INIT>,
+C<INTERNAL>,
+C<TIMEOUT>,
+C<UNSUPPORTED_PROTOCOL>,
+C<UNSUPPORTED_QUERY>,
+C<INVALID_QUERY>,
+C<CREATE_QUERY>,
+C<QUERY_CQL>,
+C<QUERY_PQF>,
+C<SORTBY>,
+C<CLONE>
+and
+C<PACKAGE>,
+each of which specifies a client-side error. Since errors may also be
+diagnosed by the server, and returned to the client, error codes may
+also take values from the BIB-1 diagnostic set of Z39.50, listed at
+the Z39.50 Maintenance Agency's web-site at
+http://www.loc.gov/z3950/agency/defns/bib1diag.html
+
+All error-codes, whether client-side from the C<ZOOM::Error>
+enumeration or server-side from the BIB-1 diagnostic set, can be
+translated into human-readable messages by passing them to the
+C<ZOOM::diag_str()> utility function.
+
+=head2 ZOOM::Event
+
+ if ($conn->last_event() == ZOOM::Event::CONNECT) {
+ print "Connected!\n";
+ }
+
+In applications that need it - mostly complex multiplexing
+applications - The C<ZOOM::Connection::last_event()> method is used to
+return an indication of the last event that occurred on a particular
+connection. It always returns a value drawn from this enumeration,
+that is, one of C<NONE>, C<CONNECT>, C<SEND_DATA>, C<RECV_DATA>,
+C<TIMEOUT>, C<UNKNOWN>, C<SEND_APDU>, C<RECV_APDU>, C<RECV_RECORD> or
+C<RECV_SEARCH>.
+
+You almost certainly don't need to know about this. Frankly, I'm not
+sure how to use it myself.