NAME
Net::Z3950::ResultSet - result set received in response to a Z39.50 search
SYNOPSIS
if ($conn->op() == Net::Z3950::Op::Search) {
$rs = $conn->resultSet();
$size = $rs->size();DESCRIPTION
A ResultSet object represents the set of records found by a Z39.50 server in response to a search. At any given time, none, some or all of the records may have been physcially transferred to the client; a cache is maintained.
Note that there is no constructor for this class (or at least, none that I'm going to tell you about :-) ResultSet objects are always created by the Net::Z3950 module itself, and are returned to the caller via the Net::Z3950::Connection class's resultSet() method.
METHODS
size()
$nrecords = $rs->size();Returns the number of records in the result set $rs
subqueryCount()
$subquery = $rs->subqueryCount();Returns hit count of subquery terms as a hash reference containing (term, count) pairs, if the server returned this information. If the information is not available, an undefined value is returned.
present()
$rs->present($start, $count) or die "failed: $rs->{errcode}\n";Causes any records in the specified range that are not yet in the cache to be retrieved from the server. By calling this method before retrieving individual records with record(), you avoid sending lots of small requests for single records across the network. In asynchronous mode, present() just schedules the records for retrieval.
Note that $start is indexed from 1.
In synchronous mode, returns 1 if the records were successfully retrieved, 0 if an error occurred. In asynchronous mode, returns 1 if new requests were queued, 0 if all of the requested records had already been queued.
record()
$rec = $rs->record($n);Returns a reference to $nth record in the result set $rs, if the content of that record is known. Valid values of $n range from 1 to the return value of the size() method.
If the record is not available, an undefined value is returned, and diagnostic information made available via $rs's errcode() and addinfo() methods.
As a special case, when the connection is anychronous, the errcode() may be zero, indicating simply that the record has not yet been fetched from the server. In this case, the calling code should try again later. (How much later? As a rule of thumb, after it's done ``something else'', such as request another record or issue another search.) This can never happen in synchronous mode.
records()
@records = $rs->records();
foreach $rec (@records) {
print $rec->render();
}This utility method returns a list of all the records in the result set I$<rs>. Because Perl arrays are indexed from zero, the first record is $records[0], the second is $records[1], etc.
If not all the records associated with $rs have yet been transferred from the server, then they need to be transferred at this point. This means that the records() method may block, and so is not recommended for use in applications that interact with multiple servers simultaneously. It does also have the side-effect that subsequent invocations of the record() method will always immediately return either a legitimate record or a ``real error'' rather than a ``not yet'' indicator.
If an error occurs, an empty list is returned. Since this is also what's returned when the search had zero hits, well-behaved applications will consult $rs-size()> in these circumstances to determine which of these two conditions pertains. After an error has occurred, details may be obtained via the result set's errcode() and addinfo() methods.
If a non-empty list is returned, then individual elements of that list may still be undefined, indicating that corresponding record could not be fetched. In order to get more information, it's necessary to attempt to fetch the record using the record() method, then consult the errcode() and addinfo() methods.
Unwarranted personal opinion: all in all, this method is a pleasant short-cut for trivial programs to use, but probably carries too many caveats to be used extensively in serious applications. You may want to take a look at present() and the prefetch option instead.
AS OF RELEASE 0.31, THIS METHOD IS NOW DEPRECATED. PLEASE USE record() INSTEAD.
delete()
$ok = $rs->delete();
if (!$ok) {
print "can't delete: ", $rs->errmsg(), "\n";
}Requests the server to delete the result set corresponding to $rs. Return non-zero on success, zero on failure.
errcode(), addinfo(), errmsg()
if (!defined $rs->record($i)) {
print "error ", $rs->errcode(), " (", $rs->errmsg(), ")\n";
print "additional info: ", $rs->addinfo(), "\n";
}When a result set's record() method returns an undefined value, indicating an error, it also sets into the result set the BIB-1 error code and additional information returned by the server. They can be retrieved via the errcode() and addinfo() methods.
As a convenience, $rs-errmsg()> is equivalent to Net::Z3950::errstr($rs-errcode())>.
option()
$value = $rs->option($type);
$value = $rs->option($type, $newval);Returns $rs's value of the standard option $type, as registered in $rs itself, in the connection across which it was created, in the manager which controls that connection, or in the global defaults.
If $newval is specified, then it is set as the new value of that option in $rs, and the option's old value is returned.
AUTHOR
Mike Taylor <mike@indexdata.com>
First version Sunday 28th May 2000.