Fix ZOOM::Connection::new so that options are handled in accordance

[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;
@@ -11,7 +11,8 @@ ZOOM - Perl extension implementing the ZOOM API for Information Retrieval
 
  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();
@@ -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,
+                               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
@@ -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
 
+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
@@ -593,19 +605,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
@@ -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?
 
+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);
@@ -822,7 +864,7 @@ thrown if the server cannot execute the requested operations; and
 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()>.
@@ -866,7 +908,7 @@ http://indexdata.com/yaz/doc/zoom.ext.tkl
 
 =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