A connection object represents an established connection to a particular server on a particular port, together with options such as the default database in which to search. It maintains a queue of outstanding requests (searches executed against it, fetches executed against result sets instantiated against it) etc.

Creates and returns a new connection, under the control of the manager $mgr, to the server on the specified $host and $port. If the $port argument is omitted, the z3950 service is used; if this is not defined, port 210 is used.

The manager argument may be omitted, in which case, the connection is created under the control of a ``default manager'', a reference to which may be subsequently retrieved with the manager() method. Multiple connections made with no explicitly-specified manager in this way will all share the same implicit manager. The default manager is initially in synchronous mode. If you don't understand what this paragraph is on about, you should feel free to ignore it.

Unix-domain socket connections can be made by specifying unix as the hostname and the path to the socket file as the port.

If the connection is created in synchronous mode, (or, if the constructor call doesn't specify a mode, if the manager controlling the new connection is synchronous), then the constructor does not return until either the connection is forged or an error occurs in trying to do so. (In the latter case, error information is stored in the manager structure.) If the connection is asynchronous, then the new object is created and returned before the connection is forged; this will happen in parallel with subsequent actions.

This is a lie: connecting is always done synchronously.

If a connection cannot be forged, then $! contains an error code indicating what went wrong: this may be one of the usual system error codes such as ECONNREFUSED (if there is no server running at the specified address); alternatively, it may be set to the distinguished value -1 if the TCP/IP connection was correctly forged, but the Z39.50 Init failed.

Any of the standard options (including asynchronous mode) may be specified as additional arguments. Specifically:

Returns a reference to the manager controlling $conn. If $conn was created with an explicit manager, then this method will always return that function; otherwise, it returns a reference to the single global ``default manager'' shared by all other connections.

Inititiates a new search against the Z39.50 server to which $conn is connected. Since this can never fail (:-), it die()s if anything goes wrong. But that will never happen. (``Surely the odds of that happening are million to one, doctor?'')

The query itself can be specified in a variety of ways:

A Net::Z3950::Query object may be passed in.

A query-type option may be passed in, together with the query string itself as its argument. Currently recognised query types are -ccl (using the standard CCL query syntax, interpreted by the server), -ccl2rpn (CCL query compiled by the client into a type-1 query), -prefix (using Index Data's prefix query notation, described at http://indexdata.dk/yaz/doc/tools.php#PQF ) and -cql (passing a CQL query straight through to the server).

A query string alone may be passed in. In this case, it is interpreted according to the query type previously established as a default for $conn or its manager.

The various query types are described in more detail in the documentation of the Net::Z3950::Query class.

### The Query class does not yet, and might never, exist.

Some broken Z39.50 server will fault a search but not provide any diagnostic records. The correct fix for this problem is of course to poke the providers of those servers in the back of the knee with a teaspoon until they fix their products. But since this is not always practical, Net::Z3950 provides a dummy diagnostic record in this case, with error-code 3 (``unsupported search'') and additional information set to ``no diagnostic records supplied by server''.

Executes a scan against the Z39.50 server to which $conn is connected. The scan parameters are represented by a query which is analysed for the term itself and the access-point in which it should occur. This query can be specified in the same ways as for startSearch().

When a connection has been returned from the Net::Z3950::Manager class's wait() method, it's known that something has happened to it. This method may then be called to find out what. It returns one of the following values:

When an error is known to have occurred on a connection, the error code (from the BIB-1 diagnosic set) can be retrieved via the errcode() method, any additional information via the addinfo() method, and the operation that was being attempted when the error occurred via the errop() method. (The error operation returned takes one of the values that may be returned from the op() method.)

When a connection is known to have received a search response, the response may be accessed via the connection's searchResponse(), and the search result may be accessed via the connection's resultSet() method.

But in general this won't work, because $conn is not the only reference to the connection object: when it goes out of scope, the connection is not destroyed because its manager still holds a reference to it. So use $conn-close()> (just before the close brace in the example above) to let the connection know it's done with.