From 8909986d78c95958d1f63217050afde991109e0a Mon Sep 17 00:00:00 2001 From: mike Date: Thu, 24 Nov 2005 17:35:29 +0000 Subject: [PATCH] Much new text. --- lib/ZOOM.pod | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 92 insertions(+), 5 deletions(-) diff --git a/lib/ZOOM.pod b/lib/ZOOM.pod index 07746d7..176f05c 100644 --- a/lib/ZOOM.pod +++ b/lib/ZOOM.pod @@ -1,4 +1,4 @@ -# $Id: ZOOM.pod,v 1.10 2005-11-18 17:55:08 mike Exp $ +# $Id: ZOOM.pod,v 1.11 2005-11-24 17:35:29 mike Exp $ use strict; use warnings; @@ -501,12 +501,37 @@ scenario where you'd want to do this. =head4 sort() - if ($rs->sort("yaz", "1=4 >i") < 0) { + if ($rs->sort("yaz", "1=4 >i 1=21 >s") < 0) { die "sort failed"; } -Sorts the ResultSet in place ### - +Sorts the ResultSet in place (discarding any cached records, as they +will in general be sorted into a different position). There are two +arguments: the first is a string indicating the type of the +sort-specification, and the second is the specification itself. + +The C method returns 0 on success, or -1 if the +sort-specification is invalid. + +At present, the only supported sort-specification type is C. +Such a specification consists of a space-separated sequence of keys, +each of which itself consists of two space-separated words (so that +the total number of words in the sort-specification is even). The two +words making up each key are a field and a set of flags. The field +can take one of two forms: if it contains an C<=> sign, then it is a +BIB-1 I=I pair specifying which field to sort +(e.g. C<1=4> for a title sort); otherwise it is sent for the server to +interpret as best it can. The word of flags is made up from one or +more of the following: C for case sensitive, C for case +insensitive; C<<> for ascending order and C> for descending +order. + +For example, the sort-specification in the code-fragment above will +sort the records in C<$rs> case-insensitively in descending order of +title, with records having equivalent titles sorted case-sensitively +in ascending order of subject. (The BIB-1 access points 4 and 21 +represent title and subject respectively.) + =head4 destroy() $rs->destroy() @@ -516,7 +541,69 @@ reuse a ResultSet that has been Ced. =head2 ZOOM::Record -I<###> + $rec = $rs->record($i); + print $rec->render(); + $raw = $rec->raw(); + $marc = new_from_usmarc MARC::Record($raw); + print "Record title is: ", $marc->title(), "\n"; + +A Record object represents a record that has been retrived from the +server. + +There is no C method nor any other explicit constructor. The +only way to create a new Record is by using C (or +C, or C) on a ResultSet. + +In general, records are ``owned'' by their result-sets that they were +retrieved from, so they do not have to be explicitly memory-managed: +they are deallocated (and therefore can no longer be used) when the +result-set is destroyed. + +See the description of the C class in the ZOOM Abstract +API at +http://zoom.z3950.org/api/zoom-current.html#3.4 + +=head3 Methods + +=head4 render() + + print $rec->render() + +Returns a human-readable representation of the record. Beyond that, +no promises are made: careful programs should not make assumptions +about the format of the returned string. + +This method is useful mostly for debugging. + +=head4 raw() + + use MARC::Record + $raw = $rec->raw(); + $marc = new_from_usmarc MARC::Record($raw); + +Returns an opaque blob of data that is the raw form of the record. +Exactly what this is, and what you can do with it, varies depending on +the record-syntax. For example, XML records will be returned as, +well, XML; MARC records will be returned as ISO 2709-encoded blocks +that can be decoded by software such as the fine C +module; GRS-1 record will be ... gosh, what an interesting question. +But no-one uses GRS-1 any more, do they? + +=head4 clone(), destroy() + + $rec = $rs->record($i); + $newrec = $rec->clone(); + $rs->destroy(); + print $newrec->render(); + $newrec->destroy(); + +Usually, it's convenient that Record objects are owned by their +ResultSets and go away when the ResultSet is destroyed; but +occasionally you need a Record to outlive its parent and destroy it +later, explicitly. To do this, C the record, keep the new +Record object that is returned, and C it when it's no +longer needed. This is B situation in which a Record needs to +be destroyed. =head2 ZOOM::Exception -- 1.7.10.4