size()subqueryCount()present()record()records()delete()errmsg()option()
Net::Z3950::ResultSet - result set received in response to a Z39.50 search
if ($conn->op() == Net::Z3950::Op::Search) {
$rs = $conn->resultSet();
$size = $rs->size();
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.
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.
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.
Mike Taylor <mike@indexdata.com>
First version Sunday 28th May 2000.