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');
        $sr = $conn->scan('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);
        $conn = new Net::Z3950::Connection($host, $port);
        $conn = new Net::Z3950::Connection($mgr, "unix", $path);
        $conn = new Net::Z3950::Connection("unix", $path);

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:

        $conn = new Net::Z3950::Connection($mgr, $host, $port, async => 1);

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:

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''.

startScan()

        $conn->startScan($scan);
        $conn->startScan(-prefix => '@attr 1=5 programming');
        $conn->startScan('@attr 1=5 programming');

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().

search()

        $rs = $conn->search($srch);

This method performs a blocking search, returning a reference to the result set generated by the server. It takes the same arguments as startSearch()

scan()

    $sr = $conn->scan($scan);

This method performs a blocking scan, returning a reference to the scan result generated by the server. It takes the same arguments as startScan()

The returned structure is a Net::Z3950::APDU::ScanResponse which can be pulled apart by inspection. That may not be the nicest possible interface.

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, or the raw APDU object may be obtained via searchResponse().

Net::Z3950::Op::Get
One or more result-set records have become available. They may be obtained via the record() method of the appropriate result set.

Net::Z3950::Op::Scan
A scan response was received. The scan-set may be obtained via the scanSet() method described below, or the raw APDU object may be obtained via scanResponse().

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.)

The meanings of the BIB-1 diagnostics are described at on the Z39.50 Maintenance Agency web-site at http://lcweb.loc.gov/z3950/agency/defns/bib1diag.html

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.

scanResponse(), scanSet()

        if ($op == Net::Z3950::Op::Scan) {
                $sr = $conn->scanResponse();
                $ss = $conn->scanSet();

When a connection is known to have received a scan response, the response may be accessed via the connection's scanResponse(), and the scan-set may be accessed via the connection's scanSet() 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.

AUTHOR

Mike Taylor <mike@indexdata.com>

First version Tuesday 23rd May 2000.

SEE ALSO

Net::Z3950::Query