NAME

Net::Z3950::DBIServer::ResultSet - in-progress result set objects for DBIServer

SYNOPSIS

        $rs = new Net::Z3950::DBIServer::ResultSet($this->{dbh}, "*",
                                                   $SQLcond, $config);
        $n = $rs->count();
        for ($i = 0; $i < $n; $i++) {
            $hashref = $rs->fetch($i);
        }

DESCRIPTION

Represents a result set in the process of being inspected by a client. The initial search is executed at construction time, and the number of record satisfying the condition stored and made available. Thereafter, records may be fetched via a random-access interface.

In truth, records must be fetched in order - that's how the DBI interface, and RDBMSs in general work - and that's how we expect ResultSets to be used most of the time; but we give the illusion of random access by reading ahead to the required record if asked for one further ahead than the next in sequence; and by caching a few of the more recently-read records after reading them, to support requests for earlier records. The upshot is that code like

        for ($i = $n-1; $i >= 0; $i--) {
            $hashref = $rs->fetch($i);
        }

will work provided that $n is not ``too large'', which means larger than the record cache associated with the result set. This may be configured using the configuration file's cachesize directive: the default value is 10. If the value is set to zero, this means never to discard records.

METHODS

`new()`

        $rs = new Net::Z3950::DBIServer::ResultSet($dbh, $config, $cond);

Creates and returns a new ResultSet for records from the DBI connection handle $dbh, containing the specified $fields (expressed as a comma-separated list), satisfying the condition $cond and interpreted by the database-specific configuration segment $config,

$config must be a reference to a Net::Z3950::DBIServer::Config::PerDB object - one of the objects in the array returned as a Net::Z3950::DBIServer::Config object from that class's constructor.

`config()`

        $config = $rs->config();

Returns the database-specific configuration segment with which the result set was created.

`count()`

        $config = $rs->count();

Returns the number of records in the result set.

`fetch()`

        $hashref = $rs->fetch($offset);
        foreach $key (keys %$hashref) {
                print($key, "->", $hashref->{$key}, "\n");
        }

Returns a reference to hash mapping fieldnames to values for record number $offset (counting starts at 0), if that information is known. If it can't be obtained (most likely because the underlying DBI statement handle has already read past the requested record, and it's fallen out of the result set's cache), then an Exception is thrown representing BIB-1 diagnostic 33 (``Resources exhausted - valid subset of results available'').

AUTHOR

Mike Taylor <mike@miketaylor.org.uk>

First version Saturday 23rd February 2002.