+ $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");
+ $conn = new ZOOM::Connection("indexdata.dk", 210,
+ databaseName => "mydb",
+ preferredRecordSyntax => "marc");
+
+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
+
+When the two-option form is used (which may be done using a vacuous
+second argument of zero), any number of additional argument pairs may
+be provided, which are interpreted as key-value pairs to be set as
+options after the Connection object is created but before it is
+connected to the server. This is a convenient way to set options,
+including those that must be set before connecting such as
+authentication tokens.
+
+The server-name string is 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
+
+SRU connection over HTTP.
+
+=back
+
+If the C<http> scheme is used, the particular SRU flavour to be used
+may be specified by the C<sru> option, which takes the following
+values:
+
+=over 4
+
+=item soap
+
+SRU over SOAP (i.e. what used to be called SRW).
+This is the default.
+
+=item get
+
+"SRU Classic" (i.e. SRU over HTTP GET).
+
+=item post
+
+SRU over HTTP POST.
+
+=back
+
+If an error occurs, an exception is thrown. This may indicate a
+networking problem (e.g. the host is not found or unreachable), or a
+protocol-level problem (e.g. a Z39.50 server rejected the Init
+request).
+
+=head4 create() / connect()
+
+ $options = new ZOOM::Options();
+ $options->option(implementationName => "my client");
+ $options->option(implementationId => 12345);
+ $conn = create ZOOM::Connection($options)
+ # or
+ $conn = create ZOOM::Connection(implementationName => "my client",
+ implementationId => 12345);
+
+ $conn->connect($host, 0);
+
+The usual Connection constructor, C<new()> brings a new object into
+existence and forges the connection to the server all in one
+operation, which is often what you want. For applications that need
+more control, however, these two methods separate the two steps,
+allowing additional steps in between such as the setting of options.
+
+C<create()> creates and returns a new Connection object, which is
+I<not> connected to any server. It may be passed an options block, of
+type C<ZOOM::Options> (see below), into which options may be set
+before or after the creation of the Connection. Alternatively and
+equivalently, C<create()> may be passed a list of key-value option
+pairs directly. The connection to the server may then be forged by
+the C<connect()> method, the arguments of which are the same as those
+of the C<new()> constructor.
+
+=head4 error_x() / errcode() / errmsg() / addinfo() / diagset()
+
+ ($errcode, $errmsg, $addinfo, $diagset) = $conn->error_x();
+ $errcode = $conn->errcode();
+ $errmsg = $conn->errmsg();
+ $addinfo = $conn->addinfo();
+ $diagset = $conn->diagset();
+
+These methods may be used to obtain information about the last error
+to have occurred on a connection - although typically they will not
+been used, as the same information is available through the
+C<ZOOM::Exception> that is thrown when the error occurs. The
+C<errcode()>,
+C<errmsg()>,
+C<addinfo()>
+and
+C<diagset()>
+methods each return one element of the diagnostic, and
+C<error_x()>
+returns all four at once.
+
+See the C<ZOOM::Exception> for the interpretation of these elements.
+
+=head4 exception()
+
+ die $conn->exception();
+
+C<exception()> returns the same information as C<error_x()> in the
+form of a C<ZOOM::Exception> object which may be thrown or rendered.
+If no error occurred on the connection, then C<exception()> returns an
+undefined value.
+
+=head4 check()
+
+ $conn->check();
+
+Checks whether an error is pending on the connection, and throw a
+C<ZOOM::Exception> object if so. Since errors are thrown as they
+occur for synchronous connections, there is no need ever to call this
+except in asynchronous applications.
+
+=head4 option() / option_binary()
+
+ print("server is '", $conn->option("serverImplementationName"), "'\n");
+ $conn->option(preferredRecordSyntax => "usmarc");
+ $conn->option_binary(iconBlob => "foo\0bar");
+ die if length($conn->option_binary("iconBlob") != 7);
+
+Objects of the Connection, ResultSet, ScanSet and Package classes
+carry with them a set of named options which affect their behaviour in
+certain ways. See the ZOOM-C options documentation for details:
+
+Connection options are listed at
+http://indexdata.com/yaz/doc/zoom.tkl#zoom.connections
+
+These options are set and fetched using the C<option()> method, which
+may be called with either one or two arguments. In the two-argument
+form, the option named by the first argument is set to the value of
+the second argument, and its old value is returned. In the
+one-argument form, the value of the specified option is returned.
+
+For historical reasons, option values are not binary-clean, so that a
+value containing a NUL byte will be returned in truncated form. The
+C<option_binary()> method behaves identically to C<option()> except
+that it is binary-clean, so that values containing NUL bytes are set
+and returned correctly.
+
+=head4 search() / search_pqf()
+
+ $rs = $conn->search(new ZOOM::Query::CQL('title=dinosaur'));
+ # The next two lines are equivalent
+ $rs = $conn->search(new ZOOM::Query::PQF('@attr 1=4 dinosaur'));
+ $rs = $conn->search_pqf('@attr 1=4 dinosaur');
+
+The principal purpose of a search-and-retrieve protocol is searching
+(and, er, retrieval), so the principal method used on a Connection
+object is C<search()>. It accepts a single argument, a C<ZOOM::Query>
+object (or, more precisely, an object of a subclass of this class);
+and it creates and returns a new ResultSet object representing the set
+of records resulting from the search.
+
+Since queries using PQF (Prefix Query Format) are so common, we make
+them a special case by providing a C<search_pqf()> method. This is
+identical to C<search()> except that it accepts a string containing
+the query rather than an object, thereby obviating the need to create
+a C<ZOOM::Query::PQF> object. See the documentation of that class for
+information about PQF.
+
+=head4 scan() / scan_pqf()
+
+ $rs = $conn->scan(new ZOOM::Query::CQL('title=dinosaur'));
+ # The next two lines are equivalent
+ $rs = $conn->scan(new ZOOM::Query::PQF('@attr 1=4 dinosaur'));
+ $rs = $conn->scan_pqf('@attr 1=4 dinosaur');
+
+Many Z39.50 servers allow you to browse their indexes to find terms to
+search for. This is done using the C<scan> method, which creates and
+returns a new ScanSet object representing the set of terms resulting
+from the scan.
+
+C<scan()> takes a single argument, but it has to work hard: it
+specifies both what index to scan for terms, and where in the index to
+start scanning. What's more, the specification of what index to scan
+includes multiple facets, such as what database fields it's an index
+of (author, subject, title, etc.) and whether to scan for whole fields
+or single words (e.g. the title ``I<The Empire Strikes Back>'', or the
+four words ``Back'', ``Empire'', ``Strikes'' and ``The'', interleaved
+with words from other titles in the same index.
+
+All of this is done by using a Query object representing a query of a
+single term as the C<scan()> argument. The attributes associated with
+the term indicate which index is to be used, and the term itself
+indicates the point in the index at which to start the scan. For
+example, if the argument is the query C<@attr 1=4 fish>, then
+
+=over 4
+
+=item @attr 1=4
+
+This is the BIB-1 attribute with type 1 (meaning access-point, which
+specifies an index), and type 4 (which means ``title''). So the scan
+is in the title index.
+
+=item fish
+
+Start the scan from the lexicographically earliest term that is equal
+to or falls after ``fish''.
+
+=back
+
+The argument C<@attr 1=4 @attr 6=3 fish> would behave similarly; but
+the BIB-1 attribute 6=3 mean completeness=``complete field'', so the
+scan would be for complete titles rather than for words occurring in
+titles.
+
+This takes a bit of getting used to.
+
+The behaviour is C<scan()> is affected by the following options, which
+may be set on the Connection through which the scan is done:
+
+=over 4
+
+=item number [default: 10]
+
+Indicates how many terms should be returned in the ScanSet. The
+number actually returned may be less, if the start-point is near the
+end of the index, but will not be greater.
+
+=item position [default: 1]
+
+A 1-based index specifying where in the returned list of terms the
+seed-term should appear. By default it should be the first term
+returned, but C<position> may be set, for example, to zero (requesting
+the next terms I<after> the seed-term), or to the same value as
+C<number> (requesting the index terms I<before> the seed term).
+
+=item stepSize [default: 0]
+
+An integer indicating how many indexed terms are to be skipped between
+each one returned in the ScanSet. By default, no terms are skipped,
+but overriding this can be useful to get a high-level overview of the
+index.
+
+Since scans using PQF (Prefix Query Format) are so common, we make
+them a special case by providing a C<scan_pqf()> method. This is
+identical to C<scan()> except that it accepts a string containing the
+query rather than an object, thereby obviating the need to create a
+C<ZOOM::Query::PQF> object.
+
+=back
+
+=head4 package()
+
+ $p = $conn->package();
+ $o = new ZOOM::Options();
+ $o->option(databaseName => "newdb");
+ $p = $conn->package($o);
+
+Creates and returns a new C<ZOOM::Package>, to be used in invoking an
+Extended Service. An options block may optionally be passed in. See
+the C<ZOOM::Package> documentation.
+
+=head4 last_event()
+
+ if ($conn->last_event() == ZOOM::Event::CONNECT) {
+ print "Connected!\n";
+ }
+
+Returns a C<ZOOM::Event> enumerated value indicating the type of the
+last event that occurred on the connection. This is used only in
+complex asynchronous applications - see the sections below on the
+C<ZOOM::Event> enumeration and asynchronous applications.
+
+=head4 destroy()
+
+ $conn->destroy()
+
+Destroys a Connection object, tearing down any low-level connection
+associated with it and freeing its resources. It is an error to reuse
+a Connection that has been C<destroy()>ed.