X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=lib%2FZOOM.pod;h=20694d4c00906612ff34378853bbf7ac2e2c86f8;hb=202fa72d1f5647efa7299a32df31de8f64bf7733;hp=337f080abab009add5ab598ffeda5c4b0216b83c;hpb=5fd91c3a88f5d2d9e8f11f69ec620fba5dc15af0;p=ZOOM-Perl-moved-to-github.git

diff --git a/lib/ZOOM.pod b/lib/ZOOM.pod
index 337f080..20694d4 100644
--- a/lib/ZOOM.pod
+++ b/lib/ZOOM.pod
@@ -1,4 +1,4 @@
-# $Id: ZOOM.pod,v 1.19 2005-12-13 15:30:26 mike Exp $
+# $Id: ZOOM.pod,v 1.21 2005-12-13 16:22:41 mike Exp $
 
 use strict;
 use warnings;
@@ -38,8 +38,8 @@ API such as ZOOM is that all implementations should be compatible
 anyway; but knowing that the same code is running is reassuring.)
 
 The ZOOM module provides two enumerations (C<ZOOM::Error> and
-C<ZOOM::Event>), a single utility function C<diag_str()> in the C<ZOOM>
-package itself, and eight classes:
+C<ZOOM::Event>), two utility functions C<diag_str()> and C<event()> in
+the C<ZOOM> package itself, and eight classes:
 C<ZOOM::Exception>,
 C<ZOOM::Options>,
 C<ZOOM::Connection>,
@@ -76,7 +76,7 @@ In general, method calls throw an exception if anything goes wrong, so
 you don't need to test for success after each call.  See the section
 below on the Exception class for details.
 
-=head1 UTILITY FUNCTION
+=head1 UTILITY FUNCTIONS
 
 =head2 ZOOM::diag_str()
 
@@ -92,6 +92,21 @@ C<ZOOM::Connection::errcode()>,
 irrespective of whether it is a member of the C<ZOOM::Error>
 enumeration or drawn from the BIB-1 diagnostic set.
 
+=head2 ZOOM::event()
+
+B<Warning: lark's vomit.  Do not read this.>
+
+ $which = ZOOM::event([ $conn1, $conn2, $conn3 ]);
+
+Used only in complex asynchronous applications, this function takes a
+reference to a list of Connection objects, waits until an event
+occurs on any one of them, and returns an integer indicating which of
+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<This function is not yet implemented.>
+
 =head1 CLASSES
 
 The eight ZOOM classes are described here in ``sensible order'':
@@ -368,6 +383,19 @@ Creates and returns a new C<ZOOM::Package>, to be used in invoking an
 Extended Service.  An options block may optionally be passed in.  See
 the C<ZOOM::Package> documentation.
 
+=head4 last_event()
+
+ if ($conn->last_event() == ZOOM::Event::CONNECT) {
+     print "Connected!\n";
+ }
+
+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
+<ZOOM::Event> for more information.
+
+B<Beware - this method has not been tested>
+
 =head4 destroy()
 
  $conn->destroy()
@@ -979,23 +1007,72 @@ They are an extension to that specification.
 
 =head4 new()
 
-I<###>
+ $o1 = new ZOOM::Options();
+ $o1and2 = new ZOOM::Options($o1);
+ $o3 = new ZOOM::Options();
+ $o1and3and4 = new ZOOM::Options($o1, $o3);
+
+Creates and returns a new option set.  One or two (but no more)
+existing option sets may be passed as arguments, in which case they
+become ``parents'' of the new set, which thereby ``inherits'' their
+options, the values of the first parent overriding those of the second
+when both have a value for the same key.  An option set that inherits
+from a parent that has its own parents also inherits the grandparent's
+options, and so on.
 
-=head4 option()
+=head4 option() / option_binary()
 
-I<###>
+ $o->option(preferredRecordSyntax => "usmarc");
+ $o->option_binary(iconBlob => "foo\0bar");
+ die if length($o->option_binary("iconBlob") != 7);
 
-=head4 option_binary()
+These methods are used to get and set options within a set, and behave
+the same way as the same-named C<Connection> methods - see above.  As
+with the C<Connection> methods, values passed to and retrieved using
+C<option()> are interpreted as NUL-terminated, while those passed to
+and retrieved from C<option_binary()> are binary-clean.
 
-I<###>
+=head4 bool()
 
-=head4 bool() / int()
+ $o->option(x => "T");
+ $o->option(y => "F");
+ assert($o->bool("x", 1));
+ assert(!$o->bool("y", 1));
+ assert($o->bool("z", 1));
 
-I<###>
+The first argument is a key, and the second is a default value.
+Returns the value associated with the specified key as a boolean, or
+the default value if the key has not been set.  The values C<T> (upper
+case) and C<1> are considered true; all other values (including C<t>
+(lower case) and non-zero integers other than one) are considered
+false.
+
+This method is provided in ZOOM-C because in a statically typed
+language it's convenient to have the result returned as an
+easy-to-test type.  In a dynamically typed language such as Perl, this
+problem doesn't arise, so C<bool()> is nearly useless; but it is made
+available in case applications need to duplicate the idiosyncratic
+interpretation of truth and falsehood and ZOOM-C uses.
+
+=head4 int()
+
+ $o->option(x => "012");
+ assert($o->int("x", 20) == 12);
+ assert($o->int("y", 20) == 20);
+
+Returns the value associated with the specified key as an integer, or
+the default value if the key has not been set.  See the description of
+C<bool()> for why you almost certainly don't want to use this.
 
 =head4 set_int()
 
-I<###>
+ $o->set_int(x => "29");
+
+Sets the value of the specified option as an integer.  Of course, Perl
+happily converts strings to integers on its own, so you can just use
+C<option()> for this, but C<set_int()> is guaranteed to use the same
+string-to-integer conversion as ZOOM-C does, which might occasionally
+be useful.  Though I can't imagine how.
 
 =head4 set_callback()
 
@@ -1003,7 +1080,10 @@ I<###>
 
 =head4 destroy()
 
-I<###>
+ $o->destroy()
+
+Destroys an Options object, freeing its resources.  It is an error to
+reuse an Options object that has been C<destroy()>ed.
 
 =head1 ENUMERATIONS