Net::Z3950::DBIServer::ResultSet - in-progress result set objects for DBIServer
$rs = new Net::Z3950::DBIServer::ResultSet($this->{dbh}, "*", $SQLcond, $config); $n = $rs->count(); for ($i = 0; $i < $n; $i++) { $hashref = $rs->fetch($i); }
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.
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'').
Mike Taylor <mike@miketaylor.org.uk>
First version Saturday 23rd February 2002.
Net::Z3950::DBIServer
is the module that uses this.