/ 
Net-Z3950-0.14
River stage one • 1 direct dependent • 1 total dependent
/ Net::Z3950::Connection

NAME

Net::Z3950::Connection - Connection to a Z39.50 server, with request queue

SYNOPSIS

$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());
}

DESCRIPTION

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.

METHODS

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 undef, or may be omitted completely; in either 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.

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:

Net::Z3950::Op::Error

An error occurred. The details may be obtained via the errcode(), addinfo() and errop() methods described below.

Net::Z3950::Op::Init

An init response was received. The response object may be obtained via the initResponse() method described below.

Net::Z3950::Op::Search

A search response was received. The result set may be obtained via the resultSet() method described below.

Net::Z3950::Op::Get

One or more result-set records have become available. They may be obtained via the records() method described below.

errcode(), addinfo(), errop()

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::diagbib1_str($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.

records()

if ($op == Net::Z3950::Op::Get) {
	@recs = $conn->records();

When a connection is known to have some result-set records available, they may be accessed via the connection's records() method, which returns an array of zero or more Net::Z3950::Record references.

Zero records are only returned if there are no more records on the server satisfying the get() requests that have been made on the appropriate result set associated with $conn.

### What happens if the client issues several sets of get requests on the same result set, and those requests can only be satisfied by repeated PRESENT requests? This is unclear, and suggests that the interface needs rethinking. Perhaps we need a method to return a reference to a particular result set for which records have arrived? Watch this space ...

AUTHOR

Mike Taylor <mike@tecc.co.uk>

First version Tuesday 23rd May 2000.

SEE ALSO

Net::Z3950::Query