X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=lib%2FZOOM.pod;h=fd8abbf8d22728a1b6eb7d6ca11044f018a7b9a1;hb=1a18b079807428305b7376022236e901e4f576ca;hp=e2aafecad3405fbab90be964a07d6f76990e65cd;hpb=7775c1094c9b0288b2208925f0250356441f6bfd;p=ZOOM-Perl-moved-to-github.git

diff --git a/lib/ZOOM.pod b/lib/ZOOM.pod
index e2aafec..fd8abbf 100644
--- a/lib/ZOOM.pod
+++ b/lib/ZOOM.pod
@@ -1,4 +1,4 @@
-# $Id: ZOOM.pod,v 1.30 2006-03-09 12:57:19 mike Exp $
+# $Id: ZOOM.pod,v 1.33 2006-04-11 16:40:08 mike Exp $
 
 use strict;
 use warnings;
@@ -99,10 +99,10 @@ enumeration or drawn from the BIB-1 diagnostic set.
 
 =head2 ZOOM::event()
 
-B<Warning.>
-Lark's vomit.  Do not read this section.
-
- $which = ZOOM::event([ $conn1, $conn2, $conn3 ]);
+ $connsRef = [ $conn1, $conn2, $conn3 ];
+ $which = ZOOM::event($connsRef);
+ $ev = $connsRef->[$which-1]->last_event()
+     if ($which != 0);
 
 Used only in complex asynchronous applications, this function takes a
 reference to a list of Connection objects, waits until an event
@@ -111,8 +111,7 @@ the connections it occurred on.  The return value is a 1-based index
 into the list; 0 is returned if no event occurs within the longest
 timeout specified by the C<timeout> options of all the connections.
 
-B<Warning.>
-This function is not yet implemented.
+See the section below on asynchronous applications.
 
 =head1 CLASSES
 
@@ -418,11 +417,8 @@ the C<ZOOM::Package> documentation.
 
 Returns a C<ZOOM::Event> enumerated value indicating the type of the
 last event that occurred on the connection.  This is used only in
-complex asynchronous applications - see the section below on
-C<ZOOM::Event> for more information.
-
-B<Warning.>
-This method has not been tested.
+complex asynchronous applications - see the sections below on the
+C<ZOOM::Event> enumeration and asynchronous applications.
 
 =head4 destroy()
 
@@ -605,19 +601,24 @@ http://zoom.z3950.org/api/zoom-current.html#3.5
 
 =head4 render()
 
- print $rec->render()
+ print $rec->render();
+ print $rec->render("charset=latin1,utf8");
 
 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.
 
+If the optional argument is provided, then it is interpreted as in the
+C<get()> method (q.v.)
+
 This method is useful mostly for debugging.
 
 =head4 raw()
 
- use MARC::Record
+ use MARC::Record;
  $raw = $rec->raw();
  $marc = new_from_usmarc MARC::Record($raw);
+ $trans = $rec->render("charset=latin1,utf8");
 
 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
@@ -627,6 +628,31 @@ that can be decoded by software such as the fine C<Marc::Record>
 module; GRS-1 record will be ... gosh, what an interesting question.
 But no-one uses GRS-1 any more, do they?
 
+If the optional argument is provided, then it is interpreted as in the
+C<get()> method (q.v.)
+
+=head4 get()
+
+ $raw = $rec->get("raw");
+ $rendered = $rec->get("render");
+ $trans = $rec->get("render;charset=latin1,utf8");
+ $trans = $rec->get("render", "charset=latin1,utf8");
+
+This is the underlying method used by C<render()> and C<raw()>, and
+which in turn delegates to the C<ZOOM_record_get()> function of the
+underlying ZOOM-C library.  Most applications will find it more
+natural to work with C<render()> and C<raw()>.
+
+C<get()> may be called with either one or two arguments.  The
+two-argument form is syntactic sugar: the two arguments are simply
+joined with a semi-colon to make a single argument, so the third and
+fourth example invocations above are equivalent.  The second argument
+(or portion of the first argument following the semicolon) is used in
+the C<type> argument of C<ZOOM_record_get()>, as described in
+http://www.indexdata.com/yaz/doc/zoom.records.tkl
+This is useful primarily for invoking the character-set transformation
+- in the examples above, from ISO Latin-1 to UTF-8 Unicode.
+
 =head4 clone() / destroy()
 
  $rec = $rs->record($i);
@@ -1225,11 +1251,10 @@ applications - The C<ZOOM::Connection::last_event()> method is used to
 return an indication of the last event that occurred on a particular
 connection.  It always returns a value drawn from this enumeration,
 that is, one of C<NONE>, C<CONNECT>, C<SEND_DATA>, C<RECV_DATA>,
-C<TIMEOUT>, C<UNKNOWN>, C<SEND_APDU>, C<RECV_APDU>, C<RECV_RECORD> or
-C<RECV_SEARCH>.
+C<TIMEOUT>, C<UNKNOWN>, C<SEND_APDU>, C<RECV_APDU>, C<RECV_RECORD>,
+C<RECV_SEARCH> or C<ZEND>.
 
-You almost certainly don't need to know about this.  Frankly, I'm not
-sure how to use it myself.
+See the section below on asynchronous applications.
 
 =head1 LOGGING
 
@@ -1336,6 +1361,69 @@ called.
 The log-level argument may be either a numeric value, as returned from
 C<module_level()>, or a string containing the module name.
 
+=head1 ASYNCHRONOUS APPLICATIONS
+
+Although asynchronous applications are conceptually complex, the ZOOM
+support for them is provided through a very simple interface,
+consisting of one option (C<async>), one function (C<ZOOM::event()>),
+one Connection method (C<last_event()> and an enumeration
+(C<ZOOM::Event>).
+
+The approach is as follows:
+
+=over 4
+
+=item Initialisation
+
+Create several connections to the various servers, each of them having
+the option C<async> set, and with whatever additional options are
+required - e.g. the piggyback retrieval record-count can be set so
+that records will be returned in search responses.
+
+=item Operations
+
+Send searches to the connections, request records, etc.
+
+=item Event harvesting
+
+Repeatedly call C<ZOOM::event()> to discover what responses are being
+received from the servers.  Each time this function returns, it
+indicates which of the connections has fired; this connection can then
+be interrogated with the C<last_event()> method to discover what event
+has occurred, and the return value - an element of the C<ZOOM::Event>
+enumeration - can be tested to determine what to do next.  For
+example, the C<ZEND> event indicates that no further operations are
+outstanding on the connection, so any fetched records can now be
+immediately obtained.
+
+=back
+
+Here is a very short program (omitting all error-checking!) which
+demonstrates this process.  It parallel-searches two servers (or more
+of you add them the list), displaying the first record in the
+result-set of each server as soon as it becomes available.
+
+ use ZOOM;
+ @servers = ('z3950.loc.gov:7090/Voyager',
+             'bagel.indexdata.com:210/gils');
+ for ($i = 0; $i < @servers; $i++) {
+     $z[$i] = new ZOOM::Connection($servers[$i], 0,
+                                   async => 1, # asynchronous mode
+                                   count => 1, # piggyback retrieval count
+                                   preferredRecordSyntax => "usmarc");
+     $r[$i] = $z[$i]->search_pqf("mineral");
+ }
+ while (($i = ZOOM::event(\@z)) != 0) {
+     $ev = $z[$i-1]->last_event();
+     print("connection ", $i-1, ": ", ZOOM::event_str($ev), "\n");
+     if ($ev == ZOOM::Event::ZEND) {
+         $size = $r[$i-1]->size();
+         print "connection ", $i-1, ": $size hits\n";
+         print $r[$i-1]->record(0)->render()
+             if $size > 0;
+     }
+ }
+
 =head1 SEE ALSO
 
 The ZOOM abstract API,