Add asynchronous support:

[ZOOM-Perl-moved-to-github.git] / lib / ZOOM.pod

diff --git a/lib/ZOOM.pod b/lib/ZOOM.pod
index bf706ea..0617ad6 100644 (file)
--- a/lib/ZOOM.pod
+++ b/lib/ZOOM.pod
@@ -1,4 +1,4 @@
-# $Id: ZOOM.pod,v 1.27 2005-12-22 14:11:17 mike Exp $
+# $Id: ZOOM.pod,v 1.31 2006-04-03 14:08:29 mike Exp $

 
 use strict;
 use warnings;
 
 use strict;
 use warnings;

@@ -11,7 +11,8 @@ ZOOM - Perl extension implementing the ZOOM API for Information Retrieval
 
  use ZOOM;
  eval {
 
  use ZOOM;
  eval {

-     $conn = new ZOOM::Connection($host, $port)
+     $conn = new ZOOM::Connection($host, $port,
+                                  databaseName => "mydb");

      $conn->option(preferredRecordSyntax => "usmarc");
      $rs = $conn->search_pqf('@attr 1=4 dinosaur');
      $n = $rs->size();
      $conn->option(preferredRecordSyntax => "usmarc");
      $rs = $conn->search_pqf('@attr 1=4 dinosaur');
      $n = $rs->size();

@@ -159,6 +160,9 @@ http://zoom.z3950.org/api/zoom-current.html#3.2
  $conn = new ZOOM::Connection("indexdata.dk:210/gils");
  $conn = new ZOOM::Connection("tcp:indexdata.dk:210/gils");
  $conn = new ZOOM::Connection("http:indexdata.dk:210/gils");
  $conn = new ZOOM::Connection("indexdata.dk:210/gils");
  $conn = new ZOOM::Connection("tcp:indexdata.dk:210/gils");
  $conn = new ZOOM::Connection("http:indexdata.dk:210/gils");

+ $conn = new ZOOM::Connection("indexdata.dk", 210,
+                               databaseName => "mydb",
+                               preferredRecordSyntax => "marc");

 
 Creates a new Connection object, and immediately connects it to the
 specified server.  If you want to make a new Connection object but
 
 Creates a new Connection object, and immediately connects it to the
 specified server.  If you want to make a new Connection object but

@@ -170,6 +174,14 @@ argument.  In the former case, the arguments are the name and port
 number of the Z39.50 server to connect to; in the latter case, the
 single argument is a YAZ service-specifier string of the form
 
 number of the Z39.50 server to connect to; in the latter case, the
 single argument is a YAZ service-specifier string of the form
 

+When the two-option form is used (which may be done using a vacuous
+second argument of zero), any number of additional argument pairs may
+be provided, which are interpreted as key-value pairs to be set as
+options after the Connection object is created but before it is
+connected to the server.  This is a convenient way to set options,
+including those that must be set before connecting such as
+authentication tokens.
+

 =over 4
 
 =item
 =over 4
 
 =item

@@ -593,19 +605,24 @@ http://zoom.z3950.org/api/zoom-current.html#3.5
 
 =head4 render()
 
 
 =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.
 
 
 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()
 
 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);
  $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
 
 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

@@ -615,6 +632,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?
 
 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);
 =head4 clone() / destroy()
 
  $rec = $rs->record($i);

@@ -822,7 +864,7 @@ thrown if the server cannot execute the requested operations; and
 finally, destroy the package.
 
 Package options are listed at
 finally, destroy the package.
 
 Package options are listed at

-http://indexdata.com/yaz/doc/zoom.ext.html
+http://indexdata.com/yaz/doc/zoom.ext.tkl

 
 The particular options that have meaning are determined by the
 top-level operation string specified as the argument to C<send()>.
 
 The particular options that have meaning are determined by the
 top-level operation string specified as the argument to C<send()>.

@@ -866,7 +908,7 @@ http://indexdata.com/yaz/doc/zoom.ext.tkl
 
 =head4 send()
 
 
 =head4 send()
 

- $p->send("createdb");
+ $p->send("create");

 
 Sends a package to the server associated with the Connection that
 created it.  Problems are reported by throwing an exception.  The
 
 Sends a package to the server associated with the Connection that
 created it.  Problems are reported by throwing an exception.  The