Net::Z3950::Connection - Connection to a Z39.50 server, with request queue $conn = new Net::Z3950::Connection($hostname, $port); $rs = $conn->search('au=kernighan and su=unix'); # or $mgr = $conn->manager(); $conn = $mgr->wait(); if ($mgr->failed()) { die "error " . $conn->errcode() . "( " . $conn->addinfo() . ")" . " in " . Net::Z3950::opstr($conn->errop()); } 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.

new()
$conn = new Net::Z3950::Connection($mgr, $host, $port); 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 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. Any of the standard options (including synchronous or asynchronous mode) may be specified as additional arguments. Specifically: $conn = new Net::Z3950::Connection($mgr, $host, $port, mode => 'async'); Works as expected.

option()
$value = $conn->option($type); $value = $conn->option($type, $newval); Returns $conn's value of the standard option $type, as registered in $conn itself, in the manager which controls it, or in the global defaults. If $newval is specified, then it is set as the new value of that option in $conn, and the option's old value is returned.

manager()
$mgr = $conn->manager(); 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.

startSearch()
$conn->startSearch($srch); $conn->startSearch(-ccl => 'au=kernighan and su=unix'); $conn->startSearch(-prefix => '@and @attr 1=1 kernighan @attr 1=21 unix'); $conn->startSearch('@and @attr 1=1 kernighan @attr 1=21 unix'); 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) and `-prefix' (using Index Data's prefix query notation). 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.

search()
$rs = $conn->search($srch); This utility method performs a blocking search, returning a reference to the result set generated by the server. It takes the same arguments as `startSearch()'

op()
op = $conn->op(); if (op == Net::Z3950::Op::Search) { # ... 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: An error occurred. The details may be obtained via the `errcode()', `addinfo()' and `errop()' methods described below. An init response was received. The response object may be obtained via the `initResponse()' method described below. A search response was received. The result set may be obtained via the `resultSet()' method described below. One or more result-set records have become available. They may be obtained via the `records()' method described below.

errcode(), addinfo(), errop(), errmsg()
if ($conn->op() == Net::Z3950::Op::Error) { print "error number: ", $conn->errcode(), "\n"; print "error message: ", $conn->errmsg(), "\n"; print "additional info: ", $conn->errcode(), "\n"; print "in function: ", Net::Z3950::opstr($conn->errop()), "\n"; } 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.) As a convenience, `$conn-'errmsg()> is equivalent to `Net::Z3950::errstr($conn-'errcode())>.

initResponse()
if ($op == Net::Z3950::Op::Init) { $rs = $conn->initResponse(); When a connection is known to have received an init response, the response may be accessed via the connection's `initResponse()' method.

searchResponse(), resultSet()
if ($op == Net::Z3950::Op::Search) { $sr = $conn->searchResponse(); $rs = $conn->resultSet(); 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.

resultSets()
@rs = $conn->resultSets(); Returns a list of all the result sets that have been created across the connection $conn and have not subsequently been deleted.

name()
print $conn->name(); Returns a short string which can be used as the connection's "name" in text output.

close()
$conn->close(); This lets the `Net::Z3950' module know that you no longer want to use `$conn' so it can be closed. It would be nice if this could be done implicitly when `$conn' goes out of scope, as in: { $conn = new Net::Z3950::Connection($host, $port); $rs = $conn->search($query); print "found ", $rs->size(), " records\n"; } 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. Mike Taylor <mike@tecc.co.uk> First version Tuesday 23rd May 2000. `Net::Z3950::Query'