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
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.
errcode(), addinfo(), errmsg()
if (!defined $rs->record($n)) {
print "error number: ", $rs->errcode(), "\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@tecc.co.uk>
First version Sunday 28th May 2000.