r2208 - in packages/libnet-z3950-perl/trunk: . debian doc doc/Z3950
doc/html doc/html/Z3950 samples
gregor herrmann
gregoa-guest at costa.debian.org
Sat Feb 25 20:49:35 UTC 2006
Author: gregoa-guest
Date: 2006-02-25 20:49:08 +0000 (Sat, 25 Feb 2006)
New Revision: 2208
Added:
packages/libnet-z3950-perl/trunk/debian/
packages/libnet-z3950-perl/trunk/debian/README.Debian
packages/libnet-z3950-perl/trunk/debian/changelog
packages/libnet-z3950-perl/trunk/debian/compat
packages/libnet-z3950-perl/trunk/debian/control
packages/libnet-z3950-perl/trunk/debian/copyright
packages/libnet-z3950-perl/trunk/debian/docs
packages/libnet-z3950-perl/trunk/debian/rules
packages/libnet-z3950-perl/trunk/debian/watch
packages/libnet-z3950-perl/trunk/doc/Z3950.html
packages/libnet-z3950-perl/trunk/doc/Z3950/
packages/libnet-z3950-perl/trunk/doc/Z3950/APDU.html
packages/libnet-z3950-perl/trunk/doc/Z3950/Connection.html
packages/libnet-z3950-perl/trunk/doc/Z3950/Manager.html
packages/libnet-z3950-perl/trunk/doc/Z3950/Record.html
packages/libnet-z3950-perl/trunk/doc/Z3950/ResultSet.html
packages/libnet-z3950-perl/trunk/doc/Z3950/Tutorial.html
packages/libnet-z3950-perl/trunk/doc/Z3950/style.css
packages/libnet-z3950-perl/trunk/doc/html/
packages/libnet-z3950-perl/trunk/doc/html/APDU.html
packages/libnet-z3950-perl/trunk/doc/html/Connection.html
packages/libnet-z3950-perl/trunk/doc/html/Manager.html
packages/libnet-z3950-perl/trunk/doc/html/Record.html
packages/libnet-z3950-perl/trunk/doc/html/ResultSet.html
packages/libnet-z3950-perl/trunk/doc/html/Tutorial.html
packages/libnet-z3950-perl/trunk/doc/html/Z3950/
packages/libnet-z3950-perl/trunk/doc/html/Z3950/APDU.html
packages/libnet-z3950-perl/trunk/doc/html/Z3950/Connection.html
packages/libnet-z3950-perl/trunk/doc/html/Z3950/Manager.html
packages/libnet-z3950-perl/trunk/doc/html/Z3950/Record.html
packages/libnet-z3950-perl/trunk/doc/html/Z3950/ResultSet.html
packages/libnet-z3950-perl/trunk/doc/html/Z3950/Tutorial.html
packages/libnet-z3950-perl/trunk/doc/html/Z3950/style.css
packages/libnet-z3950-perl/trunk/doc/html/style.css
packages/libnet-z3950-perl/trunk/doc/pod2htmd.tmp
packages/libnet-z3950-perl/trunk/doc/pod2htmi.tmp
Modified:
packages/libnet-z3950-perl/trunk/doc/htmlify
packages/libnet-z3950-perl/trunk/samples/fetch1.pl
packages/libnet-z3950-perl/trunk/samples/multiplex.pl
packages/libnet-z3950-perl/trunk/samples/simple.pl
Log:
Load libnet-z3950-perl-0.50 into packages/libnet-z3950-perl/trunk.
Added: packages/libnet-z3950-perl/trunk/debian/README.Debian
===================================================================
--- packages/libnet-z3950-perl/trunk/debian/README.Debian 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/debian/README.Debian 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,9 @@
+libnet-z3950-perl for Debian
+----------------------------
+
+You need yaz (libyaz-dev) for the package. Get the newest version at
+http://www.indexdata.dk
+deb http://www.indexdata.dk/debian indexdata/etch released
+deb-src http://www.indexdata.dk/debian indexdata/etch released
+
+ -- gregor herrmann <gregor+debian at comodo.priv.at>, Sun, 1 Jan 2006 15:40:49 +0100
Added: packages/libnet-z3950-perl/trunk/debian/changelog
===================================================================
--- packages/libnet-z3950-perl/trunk/debian/changelog 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/debian/changelog 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,29 @@
+libnet-z3950-perl (0.50-4) unstable; urgency=low
+
+ * Initial upload to the Debian archive. (Closes: #263821)
+ * Set debhelper compatibility level to 5.
+ * Changed watch file.
+ * Removed linda override.
+ * Changed Maintainer to the Debian Perl Group before initial import to
+ the pkg-perl svn repository.
+
+ -- gregor herrmann <gregor+debian at comodo.priv.at> Sat, 25 Feb 2006 19:42:39 +0100
+
+libnet-z3950-perl (0.50-3) unstable; urgency=low
+
+ * Changed debian/control and debian/rules with dh-make-perl.
+
+ -- gregor herrmann <gregor+debian at comodo.priv.at> Mon, 2 Jan 2006 01:41:29 +0100
+
+libnet-z3950-perl (0.50-2) unstable; urgency=low
+
+ * Changed Recommends: from libmarc-perl to libmarc-record-perl
+
+ -- gregor herrmann <gregor+debian at comodo.priv.at> Sun, 1 Jan 2006 17:51:07 +0100
+
+libnet-z3950-perl (0.50-1) unstable; urgency=low
+
+ * Initial release.
+
+ -- gregor herrmann <gregor+debian at comodo.priv.at> Sun, 1 Jan 2006 15:40:49 +0100
+
Added: packages/libnet-z3950-perl/trunk/debian/compat
===================================================================
--- packages/libnet-z3950-perl/trunk/debian/compat 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/debian/compat 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1 @@
+5
Added: packages/libnet-z3950-perl/trunk/debian/control
===================================================================
--- packages/libnet-z3950-perl/trunk/debian/control 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/debian/control 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,20 @@
+Source: libnet-z3950-perl
+Section: perl
+Priority: optional
+Maintainer: Debian Perl Group <pkg-perl-maintainers at lists.alioth.debian.org>
+Uploaders: gregor herrmann <gregor+debian at comodo.priv.at>
+Build-Depends: debhelper (>= 5.0.0), libyaz-dev, perl (>= 5.8.0-7), libevent-perl
+Standards-Version: 3.6.2
+
+Package: libnet-z3950-perl
+Architecture: any
+Depends: ${shlibs:Depends}, ${misc:Depends}, ${perl:Depends}, libevent-perl
+Recommends: libmarc-record-perl
+Description: Perl interface to the Z39.50 information retrieval protocol
+ Net::Z3950.pm is an implementation of the Perl binding for ZOOM, the
+ Z39.50 Object Orientation Model. Bindings for the same abstract API
+ are available in other languages including C, C++, Java, Tcl, Visual
+ Basic, Python and Scheme. There's more about ZOOM, including the
+ specification, at http://zoom.z3950.org/
+ .
+ Homepage: http://perl.z3950.org/
Added: packages/libnet-z3950-perl/trunk/debian/copyright
===================================================================
--- packages/libnet-z3950-perl/trunk/debian/copyright 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/debian/copyright 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,24 @@
+This package was debianized by gregor herrmann <gregor+debian at comodo.priv.at> on
+Sun, 1 Jan 2006 15:40:49 +0100.
+
+It was downloaded from http://www.cpan.org/authors/id/M/MI/MIRK/
+
+Author:
+Mike Taylor <mike at perl.z3950.org>
+http://www.miketaylor.org.uk/
+
+With lots of help, encouragement, design input, etc. from
+Sebastian Hammer <quinn at indexdata.dk> and
+Adam Dickmeiss <adam at indexdata.dk>
+http://indexdata.dk/
+
+
+License:
+The Net::Z3950 module is free software, as described at
+http://www.fsf.org/philosophy/free-sw.html It is made available under the
+GNU General Public Licence, version 2: This is made explicit as of release
+0.33, but it was always the intention.
+
+The full text of the GPL is available on Debian systems in
+/usr/share/common-licenses/GPL
+
Added: packages/libnet-z3950-perl/trunk/debian/docs
===================================================================
--- packages/libnet-z3950-perl/trunk/debian/docs 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/debian/docs 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,3 @@
+README
+doc/Z3950
+
Added: packages/libnet-z3950-perl/trunk/debian/rules
===================================================================
--- packages/libnet-z3950-perl/trunk/debian/rules 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/debian/rules 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,114 @@
+#!/usr/bin/make -f
+# -*- makefile -*-
+# Sample debian/rules that uses debhelper.
+# This file was originally written by Joey Hess and Craig Small.
+# As a special exception, when this file is copied by dh-make into a
+# dh-make output file, you may use that output file without restriction.
+# This special exception was added by Craig Small in version 0.37 of dh-make.
+
+# Uncomment this to turn on verbose mode.
+#export DH_VERBOSE=1
+
+# If set to a true value then MakeMaker's prompt function will
+# always return the default without waiting for user input.
+export PERL_MM_USE_DEFAULT=1
+
+PACKAGE=$(shell dh_listpackages)
+
+ifndef PERL
+PERL = /usr/bin/perl
+endif
+
+TMP =$(CURDIR)/debian/$(PACKAGE)
+
+# Allow disabling build optimation by setting noopt in
+# $DEB_BUILD_OPTIONS
+CFLAGS = -Wall -g
+ifneq (,$(findstring noopt,$(DEB_BUILD_OPTIONS)))
+ CFLAGS += -O0
+else
+ CFLAGS += -O2
+endif
+
+build: build-stamp
+build-stamp:
+ dh_testdir
+
+ # Add commands to compile the package here
+ $(PERL) Makefile.PL INSTALLDIRS=vendor
+ $(MAKE) OPTIMIZE="$(CFLAGS)" LD_RUN_PATH=""
+
+ cd doc; $(MAKE); cd ..
+
+ touch build-stamp
+
+clean:
+ dh_testdir
+ dh_testroot
+
+ # Add commands to clean up after the build process here
+ [ ! -f Makefile ] || $(MAKE) realclean
+
+ cd doc; -$(MAKE) clean; cd ..
+
+ dh_clean build-stamp install-stamp
+
+install: build install-stamp
+install-stamp:
+ dh_testdir
+ dh_testroot
+ dh_clean -k
+
+ # Add commands to install the package into debian/$PACKAGE_NAME here
+ $(MAKE) test
+ $(MAKE) install DESTDIR=$(TMP) PREFIX=/usr
+
+ dh_installdirs
+
+ # As this is a architecture dependent package, we are not
+ # supposed to install stuff to /usr/share. MakeMaker creates
+ # the dirs, we delete them from the deb:
+ rmdir --ignore-fail-on-non-empty --parents $(TMP)/usr/share/perl5
+
+ touch install-stamp
+
+# Build architecture-independent files here.
+binary-indep: build install
+
+# Build architecture-dependent files here.
+binary-arch: build install
+ dh_testdir
+ dh_testroot
+ dh_installchangelogs Changes
+ dh_installdocs
+ dh_installexamples samples/*
+# dh_install
+# dh_installmenu
+# dh_installdebconf
+# dh_installlogrotate
+# dh_installemacsen
+# dh_installpam
+# dh_installmime
+# dh_installinit
+# dh_installcron
+# dh_installinfo
+# dh_installman
+ dh_link
+ dh_strip
+ dh_compress
+ dh_fixperms
+ dh_perl
+# dh_python
+# dh_makeshlibs
+ dh_installdeb
+ dh_shlibdeps
+ dh_gencontrol
+ dh_md5sums
+ dh_builddeb
+
+
+source diff:
+ @echo >&2 'source and diff are obsolete - use dpkg-source -b'; false
+
+binary: binary-indep binary-arch
+.PHONY: build clean binary-indep binary-arch binary
Property changes on: packages/libnet-z3950-perl/trunk/debian/rules
___________________________________________________________________
Name: svn:executable
+ *
Added: packages/libnet-z3950-perl/trunk/debian/watch
===================================================================
--- packages/libnet-z3950-perl/trunk/debian/watch 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/debian/watch 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,4 @@
+# Compulsory line, this is a version 3 file
+version=3
+
+http://www.cpan.org/modules/by-module/Net/Net-Z3950-([\d.]+)\.(tar\.gz|tar|tgz)
Added: packages/libnet-z3950-perl/trunk/doc/Z3950/APDU.html
===================================================================
--- packages/libnet-z3950-perl/trunk/doc/Z3950/APDU.html 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/doc/Z3950/APDU.html 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,448 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Net::Z3950::APDU - Read-only objects representing decoded Z39.50 APDUs</title>
+<link rev="made" href="mailto:root at localhost" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#subclasses">SUBCLASSES</a></li>
+ <ul>
+
+ <li><a href="#net__z3950__apdu__initresponse">Net::Z3950::APDU::InitResponse</a></li>
+ <li><a href="#net__z3950__apdu__searchresponse">Net::Z3950::APDU::SearchResponse</a></li>
+ <li><a href="#net__z3950__apdu__scanresponse">Net::Z3950::APDU::ScanResponse</a></li>
+ <li><a href="#net__z3950__apdu__presentresponse">Net::Z3950::APDU::PresentResponse</a></li>
+ <li><a href="#net__z3950__apdu__deletersresponse">Net::Z3950::APDU::DeleteRSResponse</a></li>
+ <li><a href="#net__z3950__apdu__close">Net::Z3950::APDU::Close</a></li>
+ <li><a href="#net__z3950__apdu__nameplusrecordlist">Net::Z3950::APDU::NamePlusRecordList</a></li>
+ <li><a href="#net__z3950__apdu__nameplusrecord">Net::Z3950::APDU::NamePlusRecord</a></li>
+ <li><a href="#net__z3950__apdu__sutrs__net__z3950__apdu__usmarc__net__z3950__apdu__ukmarc__net__z3950__apdu__normarc__net__z3950__apdu__librismarc__net__z3950__apdu__danmarc__net__z3950__apdu__unimarc__net__z3950__apdu__mab">Net::Z3950::APDU::SUTRS, Net::Z3950::APDU::USMARC, Net::Z3950::APDU::UKMARC, Net::Z3950::APDU::NORMARC, Net::Z3950::APDU::LIBRISMARC, Net::Z3950::APDU::DANMARC, Net::Z3950::APDU::UNIMARC, Net::Z3950::APDU::MAB</a></li>
+ <li><a href="#net__z3950__apdu__taggedelement_">Net::Z3950::APDU::TaggedElement;</a></li>
+ <li><a href="#net__z3950__apdu__elementdata">Net::Z3950::APDU::ElementData</a></li>
+ <li><a href="#net__z3950__apdu__holdingsdata">Net::Z3950::APDU::HoldingsData</a></li>
+ <li><a href="#net__z3950__apdu__holdingsandcirc">Net::Z3950::APDU::HoldingsAndCirc</a></li>
+ <li><a href="#net__z3950__apdu__volumes">Net::Z3950::APDU::Volumes</a></li>
+ <li><a href="#net__z3950__apdu__holdingsandcirc">Net::Z3950::APDU::HoldingsAndCirc</a></li>
+ <li><a href="#net__z3950__apdu__circulationdata">Net::Z3950::APDU::CirculationData</a></li>
+ <li><a href="#net__z3950__apdu__holdingsandcirc">Net::Z3950::APDU::HoldingsAndCirc</a></li>
+ <li><a href="#net__z3950__apdu__diagrecs">Net::Z3950::APDU::DiagRecs</a></li>
+ <li><a href="#net__z3950__apdu__defaultdiagformat_">Net::Z3950::APDU::DefaultDiagFormat;</a></li>
+ <li><a href="#net__z3950__apdu__oid">Net::Z3950::APDU::OID</a></li>
+ <li><a href="#net__z3950__apdu__listentries">Net::Z3950::APDU::ListEntries</a></li>
+ <li><a href="#net__z3950__apdu__entry">Net::Z3950::APDU::Entry</a></li>
+ <li><a href="#net__z3950__apdu__terminfo">Net::Z3950::APDU::TermInfo</a></li>
+ <li><a href="#net__z3950__apdu__term">Net::Z3950::APDU::Term</a></li>
+ <li><a href="#net__z3950__apdu__otherinformation">Net::Z3950::APDU::OtherInformation</a></li>
+ <li><a href="#net__z3950__apdu__otherinformationunit">Net::Z3950::APDU::OtherInformationUnit</a></li>
+ <li><a href="#net__z3950__apdu__searchinforeport">Net::Z3950::APDU::SearchInfoReport</a></li>
+ <li><a href="#net__z3950__apdu__searchinforeport_s">Net::Z3950::APDU::SearchInfoReport_s</a></li>
+ <li><a href="#net__z3950__apdu__queryexpression">Net::Z3950::APDU::QueryExpression</a></li>
+ <li><a href="#net__z3950__apdu__queryexpressionterm">Net::Z3950::APDU::QueryExpressionTerm</a></li>
+ </ul>
+
+ <li><a href="#author">AUTHOR</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Net::Z3950::APDU - Read-only objects representing decoded Z39.50 APDUs</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<p><em>You probably shouldn't be reading this!</em></p>
+<pre>
+ package Net::Z3950::APDU::SomeSpecificSortOfAPDU;
+ use Net::Z3950::APDU;
+ @ISA = qw(Net::Z3950::APDU);
+ @FIELDS = qw(names of APDU fields);</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>This class provides a trivial base for the various read-only APDUs
+implemented as a part of the Net::Z3950 module. Its role is simply to
+supply named methods providing read-only access to the same-named
+fields. The set of fields is specified by the derived class's
+package-global <code>@FIELDS</code> array.</p>
+<p><em>You don't need to understand or use this class in order to use the
+Net::Z3950 module. It's purely an implementation detail. In fact, I
+probably should never even have written this documentation. Forget I
+said anything. Go and read the next section.</em></p>
+<p>
+</p>
+<hr />
+<h1><a name="subclasses">SUBCLASSES</a></h1>
+<p>The following classes are all trivial derivations of <code>Net::Z3950::APDU</code>,
+and represent specific types of APDU. Each such class is
+characterised by the set of data-access methods it supplies: these are
+listed below.</p>
+<p>Each method takes no arguments, and returns the information implied by
+its name. See the relevant sections of the Z39.50 Standard for
+information on the interpretation of this information - for example,
+section 3.2.1 (Initialization Facility) describes the elements of the
+<code>Net::Z3950::APDU::InitResponse</code> class.</p>
+<p><em>Actually, you don't need to understand or use any of these classes
+either: they're used internally in the implementation, so this
+documentation is provided as a service to those who will further
+develop this module in the future.</em></p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__initresponse">Net::Z3950::APDU::InitResponse</a></h2>
+<pre>
+ referenceId()
+ preferredMessageSize()
+ maximumRecordSize()
+ result()
+ implementationId()
+ implementationName()
+ implementationVersion()</pre>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__searchresponse">Net::Z3950::APDU::SearchResponse</a></h2>
+<pre>
+ referenceId()
+ resultCount()
+ numberOfRecordsReturned()
+ nextResultSetPosition()
+ searchStatus()
+ resultSetStatus()
+ presentStatus()
+ records()
+ additionalSearchInfo()</pre>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__scanresponse">Net::Z3950::APDU::ScanResponse</a></h2>
+<pre>
+ referenceId()
+ stepSize()
+ scanStatus()
+ numberOfEntriesReturned()
+ positionOfTerm()
+ entries()
+ diag()</pre>
+<p>The <code>diag()</code> method should be consulted when <code>scanStatus()</code> returns
+6, indicating failure; otherwise, <code>entries()</code> may be consulted.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__presentresponse">Net::Z3950::APDU::PresentResponse</a></h2>
+<pre>
+ referenceId()
+ numberOfRecordsReturned()
+ nextResultSetPosition()
+ presentStatus()
+ records()</pre>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__deletersresponse">Net::Z3950::APDU::DeleteRSResponse</a></h2>
+<pre>
+ referenceId()
+ deleteOperationStatus()</pre>
+<p>(We don't bother to decode the rest of this APDU at the moment, since
+I bet everyone calls <code>Net::Z3950::ResultSet::delete()</code> in void
+context. If anyone wants more information out of it, we can wire it
+through.)</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__close">Net::Z3950::APDU::Close</a></h2>
+<pre>
+ referenceId()
+ closeReason()
+ diagnosticInformation()</pre>
+<p>In addition, this class provides a method of no arguments,
+<code>as_text()</code>, which returns a human-readable string describing the
+reason for the close.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__nameplusrecordlist">Net::Z3950::APDU::NamePlusRecordList</a></h2>
+<p>No methods - just treat as a reference to an array of
+<code>Net::Z3950::APDU::NamePlusRecord</code></p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__nameplusrecord">Net::Z3950::APDU::NamePlusRecord</a></h2>
+<pre>
+ databaseName()
+ which()
+ databaseRecord()
+ surrogateDiagnostic()
+ startingFragment()
+ intermediateFragment()
+ finalFragment()</pre>
+<p>Only one of the last five methods will return anything - you can find
+out which one by inspecting the return value of the <code>which()</code> method,
+which always takes one of the following values:</p>
+<ul>
+<li></li>
+Net::Z3950::NamePlusRecord::DatabaseRecord
+<p></p>
+<li></li>
+Net::Z3950::NamePlusRecord::SurrogateDiagnostic
+<p></p>
+<li></li>
+Net::Z3950::NamePlusRecord::StartingFragment
+<p></p>
+<li></li>
+Net::Z3950::NamePlusRecord::IntermediateFragment
+<p></p>
+<li></li>
+Net::Z3950::NamePlusRecord::FinalFragment
+<p></p></ul>
+<p>When <code>which()</code> is <code>Net::Z3950::NamePlusRecord::DatabaseRecord</code>, the
+object returned from the <code>databaseRecord()</code> method will be a decoded
+Z39.50 EXTERNAL. Its type may be any of the following (and may be
+tested using <code>$rec->isa('Net::Z3950::Record::Whatever')</code> if necessary.)</p>
+<ul>
+<li></li>
+Net::Z3950::Record::SUTRS
+<p></p>
+<li></li>
+Net::Z3950::Record::GRS1
+<p></p>
+<li></li>
+Net::Z3950::Record::USMARC and
+similarly, Net::Z3950::Record::UKMARC, Net::Z3950::Record::NORMARC, <em>etc</em>.
+<p></p>
+<li></li>
+Net::Z3950::Record::XML
+<p></p>
+<li></li>
+Net::Z3950::Record::HTML
+<p></p>
+<li></li>
+Net::Z3950::Record::OPAC
+<p><em>### others, not yet supported</em></p>
+<p></p></ul>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__sutrs__net__z3950__apdu__usmarc__net__z3950__apdu__ukmarc__net__z3950__apdu__normarc__net__z3950__apdu__librismarc__net__z3950__apdu__danmarc__net__z3950__apdu__unimarc__net__z3950__apdu__mab">Net::Z3950::APDU::SUTRS, Net::Z3950::APDU::USMARC, Net::Z3950::APDU::UKMARC, Net::Z3950::APDU::NORMARC, Net::Z3950::APDU::LIBRISMARC, Net::Z3950::APDU::DANMARC, Net::Z3950::APDU::UNIMARC, Net::Z3950::APDU::MAB</a></h2>
+<p>No methods - just treat as an opaque chunk of data.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__taggedelement_">Net::Z3950::APDU::TaggedElement;</a></h2>
+<pre>
+ tagType()
+ tagValue()
+ tagOccurrence()
+ content()</pre>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__elementdata">Net::Z3950::APDU::ElementData</a></h2>
+<pre>
+ which()
+ numeric()
+ string()
+ oid()
+ subtree()</pre>
+<p>Only one of the last four methods will return anything - you can find
+out which one by inspecting the return value of the <code>which()</code> method,
+which always takes one of the following values:</p>
+<ul>
+<li></li>
+Net::Z3950::ElementData::Numeric
+<p></p>
+<li></li>
+Net::Z3950::ElementData::String
+<p></p>
+<li></li>
+Net::Z3950::ElementData::OID
+<p></p>
+<li></li>
+Net::Z3950::ElementData::Subtree
+<p></p>
+<li></li>
+<em>### others, not yet supported</em>
+<p></p></ul>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__holdingsdata">Net::Z3950::APDU::HoldingsData</a></h2>
+<p>No methods - just treat as a reference to an array of objects, where
+each object is either an MARC holdings record (of type
+<code>Net::Z3950::Record::USMARC</code> or similar) or a
+<code>Net::Z3950::APDU::HoldingsAndCirc</code></p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__holdingsandcirc">Net::Z3950::APDU::HoldingsAndCirc</a></h2>
+<pre>
+ typeOfRecord()
+ encodingLevel()
+ format()
+ receiptAcqStatus()
+ generalRetention()
+ completeness()
+ dateOfReport()
+ nucCode()
+ localLocation()
+ shelvingLocation()
+ callNumber()
+ shelvingData()
+ copyNumber()
+ publicNote()
+ reproductionNote()
+ termsUseRepro()
+ enumAndChron()
+ volumes()
+ circulationData()</pre>
+<p>All but the last two of these have string values, although not
+necessarily human-readable strings. <code>volumes()</code> returns a
+<code>Net::Z3950::APDU::Volumes</code> object (note the plural in the
+type-name), and <code>circulationData()</code> a
+<code>Net::Z3950::APDU::CirculationData</code>.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__volumes">Net::Z3950::APDU::Volumes</a></h2>
+<p>No methods - just treat as a reference to an array of
+<code>Net::Z3950::APDU::Volume</code>
+objects.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__holdingsandcirc">Net::Z3950::APDU::HoldingsAndCirc</a></h2>
+<pre>
+ enumeration()
+ chronology()
+ enumAndChron()</pre>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__circulationdata">Net::Z3950::APDU::CirculationData</a></h2>
+<p>No methods - just treat as a reference to an array of
+<code>Net::Z3950::APDU::CircRecord</code>
+objects.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__holdingsandcirc">Net::Z3950::APDU::HoldingsAndCirc</a></h2>
+<pre>
+ availableNow()
+ availablityDate()
+ availableThru()
+ restrictions()
+ itemId()
+ renewable()
+ onHold()
+ enumAndChron()
+ midspine()
+ temporaryLocation()</pre>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__diagrecs">Net::Z3950::APDU::DiagRecs</a></h2>
+<p>No methods - just treat as a reference to an array of object
+references. The objects will typically be of class
+<code>Net::Z3950::APDU::DefaultDiagFormat</code>, but careful callers will check
+this, since any kind of EXTERNAL may be provided instead.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__defaultdiagformat_">Net::Z3950::APDU::DefaultDiagFormat;</a></h2>
+<pre>
+ diagnosticSetId()
+ condition()
+ addinfo()</pre>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__oid">Net::Z3950::APDU::OID</a></h2>
+<p><strong>No longer exists.</strong>
+Previously this class had no methods - calling code just treated it
+as a reference to an array of integers. However, since the only thing
+anyone (including <code>Net::Z3950::Record::GRS1::render()</code>)
+ever did with it was smush it up into a string with</p>
+<pre>
+ join('.', @$oidRef)</pre>
+<p>we now just return the dot-separated OID string
+<em>not blessed into any class</em>
+(because scalars can't be blessed - only <em>references</em> to scalars,
+and we don't want the extra useless level of indirection).</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__listentries">Net::Z3950::APDU::ListEntries</a></h2>
+<p>No methods - just treat as a reference to an array of
+<code>Net::Z3950::APDU::Entry</code></p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__entry">Net::Z3950::APDU::Entry</a></h2>
+<pre>
+ termInfo()
+ surrogateDiagnostic()</pre>
+<p>Usually, <code>termInfo()</code> returns a scanned term. When it returns an
+undefined value, consult <surrogateDiagnostic()> to find out why.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__terminfo">Net::Z3950::APDU::TermInfo</a></h2>
+<pre>
+ term()
+ globalOccurrences()</pre>
+<p><em>### Lots more to come here, including displayTerm</em></p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__term">Net::Z3950::APDU::Term</a></h2>
+<pre>
+ general()
+ numeric()
+ characterString()
+ oid()
+ dateTime()
+ external()
+ integerAndUnit()
+ null()</pre>
+<p>At present only ``general'' terms are supported. The value of such a
+term may be obtained by calling <general()>. Terms of other types can
+not be obtained.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__otherinformation">Net::Z3950::APDU::OtherInformation</a></h2>
+<p>No methods - just treat as a reference to an array of
+<code>Net::Z3950::APDU::OtherInformationUnit</code></p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__otherinformationunit">Net::Z3950::APDU::OtherInformationUnit</a></h2>
+<pre>
+ which()
+ characterInfo()
+ binaryInfo()
+ externallyDefinedInfo
+ oid()</pre>
+<p>At present only ``externallyDefinedInfo'' units are supported.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__searchinforeport">Net::Z3950::APDU::SearchInfoReport</a></h2>
+<p>No methods - just treat as a reference to an array of
+<code>Net::Z3950::APDU::SearchInfoReport_s</code></p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__searchinforeport_s">Net::Z3950::APDU::SearchInfoReport_s</a></h2>
+<pre>
+ fullQuery()
+ subqueryExpression()
+ subqueryCount()</pre>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__queryexpression">Net::Z3950::APDU::QueryExpression</a></h2>
+<pre>
+ which()
+ term()
+ query()</pre>
+<p>At present only ``term'' query expressions are supported.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__queryexpressionterm">Net::Z3950::APDU::QueryExpressionTerm</a></h2>
+<pre>
+ queryTerm()</pre>
+<p>
+</p>
+<hr />
+<h1><a name="author">AUTHOR</a></h1>
+<p>Mike Taylor <<a href="mailto:mike at indexdata.com">mike at indexdata.com</a>></p>
+<p>First version Saturday 27th May 2000.</p>
+
+</body>
+
+</html>
Added: packages/libnet-z3950-perl/trunk/doc/Z3950/Connection.html
===================================================================
--- packages/libnet-z3950-perl/trunk/doc/Z3950/Connection.html 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/doc/Z3950/Connection.html 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,358 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Net::Z3950::Connection - Connection to a Z39.50 server, with request queue</title>
+<link rev="made" href="mailto:root at localhost" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#methods">METHODS</a></li>
+ <ul>
+
+ <li><a href="#new__"><code>new()</code></a></li>
+ <li><a href="#option__"><code>option()</code></a></li>
+ <li><a href="#manager__"><code>manager()</code></a></li>
+ <li><a href="#startsearch__"><code>startSearch()</code></a></li>
+ <li><a href="#startscan__"><code>startScan()</code></a></li>
+ <li><a href="#search__"><code>search()</code></a></li>
+ <li><a href="#scan__"><code>scan()</code></a></li>
+ <li><a href="#op__"><code>op()</code></a></li>
+ <li><a href="#errcode____addinfo____errop____errmsg__">errcode(), addinfo(), errop(), <code>errmsg()</code></a></li>
+ <li><a href="#initresponse__"><code>initResponse()</code></a></li>
+ <li><a href="#searchresponse____resultset__">searchResponse(), <code>resultSet()</code></a></li>
+ <li><a href="#scanresponse____scanset__">scanResponse(), <code>scanSet()</code></a></li>
+ <li><a href="#resultsets__"><code>resultSets()</code></a></li>
+ <li><a href="#name__"><code>name()</code></a></li>
+ <li><a href="#close__"><code>close()</code></a></li>
+ </ul>
+
+ <li><a href="#author">AUTHOR</a></li>
+ <li><a href="#see_also">SEE ALSO</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Net::Z3950::Connection - Connection to a Z39.50 server, with request queue</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ $conn = new Net::Z3950::Connection($hostname, $port);
+ $rs = $conn->search('au=kernighan and su=unix');
+ $sr = $conn->scan('au=kernighan and su=unix');
+ # or
+ $mgr = $conn->manager();
+ $conn = $mgr->wait();
+ if ($mgr->failed()) {
+ die "error " . $conn->errcode() .
+ "( " . $conn->addinfo() . ")" .
+ " in " . Net::Z3950::opstr($conn->errop());
+ }</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>A connection object represents an established connection to a
+particular server on a particular port, together with options such as
+the default database in which to search. It maintains a queue of
+outstanding requests (searches executed against it, fetches executed
+against result sets instantiated against it) <em>etc.</em></p>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<p>
+</p>
+<h2><a name="new__"><code>new()</code></a></h2>
+<pre>
+ $conn = new Net::Z3950::Connection($mgr, $host, $port);
+ $conn = new Net::Z3950::Connection($host, $port);
+ $conn = new Net::Z3950::Connection($mgr, "unix", $path);
+ $conn = new Net::Z3950::Connection("unix", $path);</pre>
+<p>Creates and returns a new connection, under the control of the manager
+<em>$mgr</em>, to the server on the specified <em>$host</em> and <em>$port</em>. If the
+<em>$port</em> argument is omitted, the <code>z3950</code> service is used; if this is
+not defined, port 210 is used.</p>
+<p>The manager argument may be omitted, in which
+case, the connection is created under the control of a
+``default manager'', a reference to which may be subsequently
+retrieved with the <code>manager()</code> method. Multiple connections made
+with no explicitly-specified manager in this way will all share the
+same implicit manager. The default manager is initially in
+synchronous mode. If you don't understand what this paragraph is on
+about, you should feel free to ignore it.</p>
+<p>Unix-domain socket connections can be made by specifying <code>unix</code> as
+the hostname and the path to the socket file as the port.</p>
+<p>If the connection is created in synchronous mode, (or, if the
+constructor call doesn't specify a mode, if the manager controlling
+the new connection is synchronous), then the constructor does not
+return until either the connection is forged or an error occurs in
+trying to do so. (In the latter case, error information is stored in
+the manager structure.) If the connection is asynchronous, then the
+new object is created and returned before the connection is forged;
+this will happen in parallel with subsequent actions.</p>
+<p><em>This is a lie: connecting is always done synchronously.</em></p>
+<p>If a connection cannot be forged, then <code>$!</code> contains an error code
+indicating what went wrong: this may be one of the usual system error
+codes such as ECONNREFUSED (if there is no server running at the
+specified address); alternatively, it may be set to the distinguished
+value -1 if the TCP/IP connection was correctly forged, but the Z39.50
+<code>Init</code> failed.</p>
+<p>Any of the standard options (including asynchronous
+mode) may be specified as additional arguments. Specifically:</p>
+<pre>
+ $conn = new Net::Z3950::Connection($mgr, $host, $port, async => 1);</pre>
+<p>Works as expected.</p>
+<p>
+</p>
+<h2><a name="option__"><code>option()</code></a></h2>
+<pre>
+ $value = $conn->option($type);
+ $value = $conn->option($type, $newval);</pre>
+<p>Returns <em>$conn</em>'s value of the standard option <em>$type</em>, as
+registered in <em>$conn</em> itself, in the manager which controls it, or in
+the global defaults.</p>
+<p>If <em>$newval</em> is specified, then it is set as the new value of that
+option in <em>$conn</em>, and the option's old value is returned.</p>
+<p>
+</p>
+<h2><a name="manager__"><code>manager()</code></a></h2>
+<pre>
+ $mgr = $conn->manager();</pre>
+<p>Returns a reference to the manager controlling <em>$conn</em>. If <em>$conn</em>
+was created with an explicit manager, then this method will always
+return that function; otherwise, it returns a reference to the single
+global ``default manager'' shared by all other connections.</p>
+<p>
+</p>
+<h2><a name="startsearch__"><code>startSearch()</code></a></h2>
+<pre>
+ $conn->startSearch($srch);
+ $conn->startSearch(-ccl => 'au=kernighan and su=unix');
+ $conn->startSearch(-prefix => '@and @attr 1=1 kernighan @attr 1=21 unix');
+ $conn->startSearch('@and @attr 1=1 kernighan @attr 1=21 unix');</pre>
+<p>Inititiates a new search against the Z39.50 server to which <em>$conn</em>
+is connected. Since this can never fail (:-), it <code>die()s</code> if
+anything goes wrong. But that will never happen. (``Surely the odds
+of that happening are million to one, doctor?'')</p>
+<p>The query itself can be specified in a variety of ways:</p>
+<ul>
+<li></li>
+A <code>Net::Z3950::Query</code> object may be passed in.
+<p></p>
+<li></li>
+A query-type option may be passed in, together with the query string
+itself as its argument. Currently recognised query types are <code>-ccl</code>
+(using the standard CCL query syntax, interpreted by the server),
+<code>-ccl2rpn</code> (CCL query compiled by the client into a type-1 query),
+<code>-prefix</code> (using Index Data's prefix query notation, described at
+<a href="http://indexdata.dk/yaz/doc/tools.php#PQF">http://indexdata.dk/yaz/doc/tools.php#PQF</a> )
+and <code>-cql</code> (passing a CQL query straight through to the server).
+<p></p>
+<li></li>
+A query string alone may be passed in. In this case, it is
+interpreted according to the query type previously established as a
+default for <em>$conn</em> or its manager.
+<p></p></ul>
+<p>The various query types are described in more detail in the
+documentation of the <code>Net::Z3950::Query</code> class.</p>
+<p><em>### The Query class does not yet, and might never, exist.</em></p>
+<p>Some broken Z39.50 server will fault a search but not provide any
+diagnostic records. The correct fix for this problem is of course to
+poke the providers of those servers in the back of the knee with a
+teaspoon until they fix their products. But since this is not always
+practical, <code>Net::Z3950</code> provides a dummy diagnostic record in this
+case, with error-code 3 (``unsupported search'') and additional
+information set to ``no diagnostic records supplied by server''.</p>
+<p>
+</p>
+<h2><a name="startscan__"><code>startScan()</code></a></h2>
+<pre>
+ $conn->startScan($scan);
+ $conn->startScan(-prefix => '@attr 1=5 programming');
+ $conn->startScan('@attr 1=5 programming');</pre>
+<p>Executes a scan against the Z39.50 server to which <em>$conn</em> is
+connected. The scan parameters are represented by a query which is
+analysed for the term itself and the access-point in which it should
+occur. This query can be specified in the same ways as for
+<code>startSearch()</code>.</p>
+<p>
+</p>
+<h2><a name="search__"><code>search()</code></a></h2>
+<pre>
+ $rs = $conn->search($srch);</pre>
+<p>This method performs a blocking search, returning a reference
+to the result set generated by the server. It takes the same
+arguments as <code>startSearch()</code></p>
+<p>
+</p>
+<h2><a name="scan__"><code>scan()</code></a></h2>
+<pre>
+ $sr = $conn->scan($scan);</pre>
+<p>This method performs a blocking scan, returning a reference
+to the scan result generated by the server. It takes the same
+arguments as <code>startScan()</code></p>
+<p>The returned structure is a <code>Net::Z3950::APDU::ScanResponse</code> which
+can be pulled apart by inspection. That may not be the nicest
+possible interface.</p>
+<p>
+</p>
+<h2><a name="op__"><code>op()</code></a></h2>
+<pre>
+ op = $conn->op();
+ if (op == Net::Z3950::Op::Search) { # ...</pre>
+<p>When a connection has been returned from the <code>Net::Z3950::Manager</code> class's
+<code>wait()</code> method, it's known that <em>something</em> has happened to it.
+This method may then be called to find out what. It returns one of
+the following values:</p>
+<dl>
+<dt><strong><a name="item_net_3a_3az3950_3a_3aop_3a_3aerror"><code>Net::Z3950::Op::Error</code></a></strong><br />
+</dt>
+<dd>
+An error occurred. The details may be obtained via the <code>errcode()</code>,
+<code>addinfo()</code> and <code>errop()</code> methods described below.
+</dd>
+<p></p>
+<dt><strong><a name="item_net_3a_3az3950_3a_3aop_3a_3ainit"><code>Net::Z3950::Op::Init</code></a></strong><br />
+</dt>
+<dd>
+An init response was received. The response object may be obtained
+via the <code>initResponse()</code> method described below.
+</dd>
+<p></p>
+<dt><strong><a name="item_net_3a_3az3950_3a_3aop_3a_3asearch"><code>Net::Z3950::Op::Search</code></a></strong><br />
+</dt>
+<dd>
+A search response was received. The result set may be obtained via
+the <code>resultSet()</code> method described below, or the raw APDU object may
+be obtained via <code>searchResponse()</code>.
+</dd>
+<p></p>
+<dt><strong><a name="item_net_3a_3az3950_3a_3aop_3a_3aget"><code>Net::Z3950::Op::Get</code></a></strong><br />
+</dt>
+<dd>
+One or more result-set records have become available. They may be
+obtained via the <code>record()</code> method of the appropriate result set.
+</dd>
+<p></p>
+<dt><strong><a name="item_net_3a_3az3950_3a_3aop_3a_3ascan"><code>Net::Z3950::Op::Scan</code></a></strong><br />
+</dt>
+<dd>
+A scan response was received. The scan-set may be obtained via the
+<code>scanSet()</code> method described below, or the raw APDU object may be
+obtained via <code>scanResponse()</code>.
+</dd>
+<p></p></dl>
+<p>
+</p>
+<h2><a name="errcode____addinfo____errop____errmsg__">errcode(), addinfo(), errop(), <code>errmsg()</code></a></h2>
+<pre>
+ if ($conn->op() == Net::Z3950::Op::Error) {
+ print "error number: ", $conn->errcode(), "\n";
+ print "error message: ", $conn->errmsg(), "\n";
+ print "additional info: ", $conn->errcode(), "\n";
+ print "in function: ", Net::Z3950::opstr($conn->errop()), "\n";
+ }</pre>
+<p>When an error is known to have occurred on a connection, the error
+code (from the BIB-1 diagnosic set) can be retrieved via the
+<code>errcode()</code> method, any additional information via the <code>addinfo()</code>
+method, and the operation that was being attempted when the error
+occurred via the <code>errop()</code> method. (The error operation returned
+takes one of the values that may be returned from the <code>op()</code> method.)</p>
+<p>The meanings of the BIB-1 diagnostics are described at on the Z39.50
+Maintenance Agency web-site at
+<a href="http://lcweb.loc.gov/z3950/agency/defns/bib1diag.html">http://lcweb.loc.gov/z3950/agency/defns/bib1diag.html</a></p>
+<p>As a convenience, <code>$conn-</code>errmsg()> is equivalent to
+<code>Net::Z3950::errstr($conn-</code>errcode())>.</p>
+<p>
+</p>
+<h2><a name="initresponse__"><code>initResponse()</code></a></h2>
+<pre>
+ if ($op == Net::Z3950::Op::Init) {
+ $rs = $conn->initResponse();</pre>
+<p>When a connection is known to have received an init response, the
+response may be accessed via the connection's <code>initResponse()</code>
+method.</p>
+<p>
+</p>
+<h2><a name="searchresponse____resultset__">searchResponse(), <code>resultSet()</code></a></h2>
+<pre>
+ if ($op == Net::Z3950::Op::Search) {
+ $sr = $conn->searchResponse();
+ $rs = $conn->resultSet();</pre>
+<p>When a connection is known to have received a search response, the
+response may be accessed via the connection's <code>searchResponse()</code>, and
+the search result may be accessed via the connection's <code>resultSet()</code>
+method.</p>
+<p>
+</p>
+<h2><a name="scanresponse____scanset__">scanResponse(), <code>scanSet()</code></a></h2>
+<pre>
+ if ($op == Net::Z3950::Op::Scan) {
+ $sr = $conn->scanResponse();
+ $ss = $conn->scanSet();</pre>
+<p>When a connection is known to have received a scan response, the
+response may be accessed via the connection's <code>scanResponse()</code>, and
+the scan-set may be accessed via the connection's <code>scanSet()</code>
+method.</p>
+<p>
+</p>
+<h2><a name="resultsets__"><code>resultSets()</code></a></h2>
+<pre>
+ @rs = $conn->resultSets();</pre>
+<p>Returns a list of all the result sets that have been created across
+the connection <em>$conn</em> and have not subsequently been deleted.</p>
+<p>
+</p>
+<h2><a name="name__"><code>name()</code></a></h2>
+<pre>
+ print $conn->name();</pre>
+<p>Returns a short string which can be used as the connection's ``name'' in
+text output.</p>
+<p>
+</p>
+<h2><a name="close__"><code>close()</code></a></h2>
+<pre>
+ $conn->close();</pre>
+<p>This lets the <code>Net::Z3950</code> module know that you no longer want to use
+<code>$conn</code> so it can be closed. It would be nice if this could be done
+implicitly when <code>$conn</code> goes out of scope, as in:</p>
+<pre>
+ {
+ $conn = new Net::Z3950::Connection($host, $port);
+ $rs = $conn->search($query);
+ print "found ", $rs->size(), " records\n";
+ }</pre>
+<p>But in general this won't work, because <code>$conn</code> is not the only
+reference to the connection object: when it goes out of scope, the
+connection is not destroyed because its manager still holds a
+reference to it. So use <code>$conn-</code>close()> (just before the close
+brace in the example above) to let the connection know it's done with.</p>
+<p>
+</p>
+<hr />
+<h1><a name="author">AUTHOR</a></h1>
+<p>Mike Taylor <<a href="mailto:mike at indexdata.com">mike at indexdata.com</a>></p>
+<p>First version Tuesday 23rd May 2000.</p>
+<p>
+</p>
+<hr />
+<h1><a name="see_also">SEE ALSO</a></h1>
+<p><code>Net::Z3950::Query</code></p>
+
+</body>
+
+</html>
Added: packages/libnet-z3950-perl/trunk/doc/Z3950/Manager.html
===================================================================
--- packages/libnet-z3950-perl/trunk/doc/Z3950/Manager.html 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/doc/Z3950/Manager.html 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,152 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Net::Z3950::Manager - State manager for multiple Z39.50 connections.</title>
+<link rev="made" href="mailto:root at localhost" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#methods">METHODS</a></li>
+ <ul>
+
+ <li><a href="#new__"><code>new()</code></a></li>
+ <li><a href="#option__"><code>option()</code></a></li>
+ <li><a href="#connect__"><code>connect()</code></a></li>
+ <li><a href="#wait__"><code>wait()</code></a></li>
+ <li><a href="#connections__"><code>connections()</code></a></li>
+ <li><a href="#resultsets__"><code>resultSets()</code></a></li>
+ </ul>
+
+ <li><a href="#author">AUTHOR</a></li>
+ <li><a href="#see_also">SEE ALSO</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Net::Z3950::Manager - State manager for multiple Z39.50 connections.</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ $mgr = new Net::Z3950::Manager(async => 1);
+ $conn = $mgr->connect($hostname, $port);
+ # Set up some more connections, then:
+ while ($conn = $mgr->wait()) {
+ # Handle message on $conn
+ }</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>A manager object encapsulates the Net::Z3950 module's global state -
+preferences for search parsing, preferred record syntaxes, compiled
+configuration files, <em>etc.</em> - as well as a list of references to all
+the open connections. It main role is to handle multiplexing between
+the connections that are opened on it.</p>
+<p>We would normally expect there to be just one manager object in a
+program, but I suppose there's no reason why you shouldn't make more
+if you want.</p>
+<p>Simple programs - those which therefore have no requirement for
+multiplexing, perhaps because they connect only to a single server -
+do not need explicitly to create a manager at all: an anonymous
+manager is implicitly created along with the connection.</p>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<p>
+</p>
+<h2><a name="new__"><code>new()</code></a></h2>
+<pre>
+ $mgr = new Net::Z3950::Manager();</pre>
+<p>Creates and returns a new manager. Any of the standard options may be
+specified as arguments; in addition, the following manager-specific
+options are recognised:</p>
+<dl>
+<dt><strong><a name="item_async">async</a></strong><br />
+</dt>
+<dd>
+This is 0 (false) by default, and may be set to 1 (true). The mode
+affects various details of subsequent behaviour - for example, see the
+description of the <code>Net::Z3950::Connection</code> class's <code>new()</code> method.
+</dd>
+<p></p></dl>
+<p>
+</p>
+<h2><a name="option__"><code>option()</code></a></h2>
+<pre>
+ $value = $mgr->option($type);
+ $value = $mgr->option($type, $newval);</pre>
+<p>Returns <em>$mgr</em>'s value of the standard option <em>$type</em>, as registered
+in <em>$mgr</em> or in the global defaults.</p>
+<p>If <em>$newval</em> is specified, then it is set as the new value of that
+option in <em>$mgr</em>, and the option's old value is returned.</p>
+<p>
+</p>
+<h2><a name="connect__"><code>connect()</code></a></h2>
+<pre>
+ $conn = $mgr->connect($hostname, $port);</pre>
+<p>Creates a new connection under the control of the manager <em>$mgr</em>.
+The connection will be forged to the server on the specified <em>$port</em>
+of <$hostname>.</p>
+<p>Additional standard options may be specified after the <em>$port</em>
+argument.</p>
+<p>(This is simply a sugar function to <code>Net::Z3950::Connection-</code>new()>)</p>
+<p>
+</p>
+<h2><a name="wait__"><code>wait()</code></a></h2>
+<pre>
+ $conn = $mgr->wait();</pre>
+<p>Waits for an event to occur on one of the connections under the
+control of <em>$mgr</em>, yielding control to any other event handlers that
+may have been registered with the underlying event loop.</p>
+<p>When a suitable event occurs - typically, a response is received to an
+earlier INIT, SEARCH or PRESENT - the handle of the connection on
+which it occurred is returned: the handle can be further interrogated
+with its <code>op()</code> and related methods.</p>
+<p>If the wait times out (only possible if the manager's <code>timeout</code>
+option has been set), then <code>wait()</code> returns an undefined value.</p>
+<p>
+</p>
+<h2><a name="connections__"><code>connections()</code></a></h2>
+<pre>
+ @conn = $mgr->connections();</pre>
+<p>Returns a list of all the connections that have been opened under the
+control of the manager <em>$mgr</em> and have not subsequently been closed.</p>
+<p>
+</p>
+<h2><a name="resultsets__"><code>resultSets()</code></a></h2>
+<pre>
+ @rs = $mgr->resultSets();</pre>
+<p>Returns a list of all the result sets that have been created across
+the connections associated with the manager <em>$mgr</em> and have not
+subsequently been deleted.</p>
+<p>
+</p>
+<hr />
+<h1><a name="author">AUTHOR</a></h1>
+<p>Mike Taylor <<a href="mailto:mike at indexdata.com">mike at indexdata.com</a>></p>
+<p>First version Tuesday 23rd May 2000.</p>
+<p>
+</p>
+<hr />
+<h1><a name="see_also">SEE ALSO</a></h1>
+<p>List of standard options.</p>
+<p>Discussion of the Net::Z3950 module's use of the Event module.</p>
+
+</body>
+
+</html>
Added: packages/libnet-z3950-perl/trunk/doc/Z3950/Record.html
===================================================================
--- packages/libnet-z3950-perl/trunk/doc/Z3950/Record.html 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/doc/Z3950/Record.html 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,165 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Net::Z3950::Record - base class for records retrieved from a Z39.50 server</title>
+<link rev="made" href="mailto:root at localhost" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#methods">METHODS</a></li>
+ <ul>
+
+ <li><a href="#nfields__"><code>nfields()</code></a></li>
+ <li><a href="#render__"><code>render()</code></a></li>
+ <li><a href="#rawdata__"><code>rawdata()</code></a></li>
+ </ul>
+
+ <li><a href="#subclasses">SUBCLASSES</a></li>
+ <ul>
+
+ <li><a href="#net__z3950__record__sutrs">Net::Z3950::Record::SUTRS</a></li>
+ <li><a href="#net__z3950__record__grs1">Net::Z3950::Record::GRS1</a></li>
+ <li><a href="#net__z3950__record__usmarc__net__z3950__record__ukmarc__net__z3950__record__normarc__net__z3950__record__librismarc__net__z3950__record__danmarc__net__z3950__record__unimarc">Net::Z3950::Record::USMARC, Net::Z3950::Record::UKMARC, Net::Z3950::Record::NORMARC, Net::Z3950::Record::LIBRISMARC, Net::Z3950::Record::DANMARC, Net::Z3950::Record::UNIMARC</a></li>
+ <li><a href="#net__z3950__record__xml">Net::Z3950::Record::XML</a></li>
+ <li><a href="#net__z3950__record__html">Net::Z3950::Record::HTML</a></li>
+ <li><a href="#net__z3950__record__opac">Net::Z3950::Record::OPAC</a></li>
+ <li><a href="#net__z3950__record__mab">Net::Z3950::Record::MAB</a></li>
+ <li><a href="#____others__not_yet_supported">### others, not yet supported</a></li>
+ </ul>
+
+ <li><a href="#author">AUTHOR</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Net::Z3950::Record - base class for records retrieved from a Z39.50 server</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ $rs = $conn->resultSet();
+ $rec = $rs->record($n);
+ print $rec->render();</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>A Record object represents a record retrieved from a Z39.50 server.
+In fact, the <code>Net::Z3950::Record</code> class itself is never instantiated:
+instead, the Net::Z3950 module creates objects of subclasses such as
+<code>Net::Z3950::Record::SUTRS</code>, <code>Net::Z3950::Record::GRS1</code>,
+<code>Net::Z3950::Record::USMARC</code> and <code>Net::Z3950::Record::XML</code>.
+This class defines a common interface which must be supported by all
+such subclasses.</p>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<p>
+</p>
+<h2><a name="nfields__"><code>nfields()</code></a></h2>
+<pre>
+ $count = $rec->nfields();</pre>
+<p>Returns the number of fields in the record <em>$rec</em>.</p>
+<p>
+</p>
+<h2><a name="render__"><code>render()</code></a></h2>
+<pre>
+ print $rec->render();</pre>
+<p>Returns a human-readable string representing the content of the record
+<em>$rec</em> in a form appropriate to its specific type.</p>
+<p>
+</p>
+<h2><a name="rawdata__"><code>rawdata()</code></a></h2>
+<pre>
+ $raw = $rec->rawdata();</pre>
+<p>Returns the raw form of the data in the record, which will in general
+be different in form for different record syntaxes.</p>
+<p>
+</p>
+<hr />
+<h1><a name="subclasses">SUBCLASSES</a></h1>
+<p>
+</p>
+<h2><a name="net__z3950__record__sutrs">Net::Z3950::Record::SUTRS</a></h2>
+<p>Represents a a record using the Simple Unstructured Text Record
+Syntax (SUTRS) - a simple flat string containing the record's data in
+a form suitable for presentation to humans (so that the <code>render()</code>
+and <code>rawdata()</code> methods return the same thing.)</p>
+<p>See Appendix REC.2 (Simple Unstructured Text Record Syntax) of the
+Z39.50 Standard for more information.</p>
+<p>
+</p>
+<h2><a name="net__z3950__record__grs1">Net::Z3950::Record::GRS1</a></h2>
+<p>Represents a record using Generic Record Syntax 1 (GRS1) - a list of
+tagged fields where each tag is made up of a tag type and tag value,
+and each field may be of any type, including numeric, string, and
+recursively contained sub-record. Fields may also be annotated with
+metadata, variant information <em>etc.</em></p>
+<p>See Appendix REC.5 (Generic Record Syntax 1) of the Z39.50 Standard
+for more information.</p>
+<p>
+</p>
+<h2><a name="net__z3950__record__usmarc__net__z3950__record__ukmarc__net__z3950__record__normarc__net__z3950__record__librismarc__net__z3950__record__danmarc__net__z3950__record__unimarc">Net::Z3950::Record::USMARC, Net::Z3950::Record::UKMARC, Net::Z3950::Record::NORMARC, Net::Z3950::Record::LIBRISMARC, Net::Z3950::Record::DANMARC, Net::Z3950::Record::UNIMARC</a></h2>
+<p>Represents a record using the appropriate MARC (MAchine Readable
+Catalogue) format - binary formats used extensively in libraries.</p>
+<p>For further information on the MARC formats, see the Library of
+Congress Network Development and MARC Standards Office web page at
+<a href="http://lcweb.loc.gov/marc/">http://lcweb.loc.gov/marc/</a> and the MARC module in Ed Summers's
+directory at CPAN,
+<a href="http://cpan.valueclick.com/authors/id/E/ES/ESUMMERS/">http://cpan.valueclick.com/authors/id/E/ES/ESUMMERS/</a></p>
+<p>
+</p>
+<h2><a name="net__z3950__record__xml">Net::Z3950::Record::XML</a></h2>
+<p>Represents a a record using XML (Extended Markup Language), as defined
+by the W3C. Rendering is not currently defined: this module treats
+the record as a single opaque lump of data, to be parsed by other
+software.</p>
+<p>For more information about XML, see <a href="http://www.w3.org/XML/">http://www.w3.org/XML/</a></p>
+<p>
+</p>
+<h2><a name="net__z3950__record__html">Net::Z3950::Record::HTML</a></h2>
+<p>Represents a a record using HTML (HyperText Markup Language), as
+defined by the W3C. Rendering is not currently defined: this module
+treats the record as a single opaque lump of data, to be handled by
+other software.</p>
+<p>For more information about HTML, see <a href="http://www.w3.org/MarkUp/">http://www.w3.org/MarkUp/</a></p>
+<p>
+</p>
+<h2><a name="net__z3950__record__opac">Net::Z3950::Record::OPAC</a></h2>
+<p>Represents a a record using the OPAC (Online Public Access Catalogue)
+record syntax, as defined in Appendix 5 (REC) of the Z39.50 standard
+at <a href="http://lcweb.loc.gov/z3950/agency/asn1.html#RecordSyntax-opac">http://lcweb.loc.gov/z3950/agency/asn1.html#RecordSyntax-opac</a></p>
+<p>
+</p>
+<h2><a name="net__z3950__record__mab">Net::Z3950::Record::MAB</a></h2>
+<p>Represents a record using the MAB record syntax (Maschinelles
+Austauschformat fuer Bibliotheken, <a href="ftp://ftp.ddb.de/pub/mab/);">ftp://ftp.ddb.de/pub/mab/);</a> an
+interchange format defined by Die Deutsche Bibliothek (German National
+Library).</p>
+<p>
+</p>
+<h2><a name="____others__not_yet_supported">### others, not yet supported</a></h2>
+<p>
+</p>
+<hr />
+<h1><a name="author">AUTHOR</a></h1>
+<p>Mike Taylor <<a href="mailto:mike at indexdata.com">mike at indexdata.com</a>></p>
+<p>First version Sunday 4th May 2000.</p>
+
+</body>
+
+</html>
Added: packages/libnet-z3950-perl/trunk/doc/Z3950/ResultSet.html
===================================================================
--- packages/libnet-z3950-perl/trunk/doc/Z3950/ResultSet.html 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/doc/Z3950/ResultSet.html 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,191 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Net::Z3950::ResultSet - result set received in response to a Z39.50 search</title>
+<link rev="made" href="mailto:root at localhost" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#methods">METHODS</a></li>
+ <ul>
+
+ <li><a href="#size__"><code>size()</code></a></li>
+ <li><a href="#subquerycount__"><code>subqueryCount()</code></a></li>
+ <li><a href="#present__"><code>present()</code></a></li>
+ <li><a href="#record__"><code>record()</code></a></li>
+ <li><a href="#records__"><code>records()</code></a></li>
+ <li><a href="#delete__"><code>delete()</code></a></li>
+ <li><a href="#errcode____addinfo____errmsg__">errcode(), addinfo(), <code>errmsg()</code></a></li>
+ <li><a href="#option__"><code>option()</code></a></li>
+ </ul>
+
+ <li><a href="#author">AUTHOR</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Net::Z3950::ResultSet - result set received in response to a Z39.50 search</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ if ($conn->op() == Net::Z3950::Op::Search) {
+ $rs = $conn->resultSet();
+ $size = $rs->size();</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>A ResultSet object represents the set of records found by a Z39.50
+server in response to a search. At any given time, none, some or all
+of the records may have been physcially transferred to the client; a
+cache is maintained.</p>
+<p>Note that there is no constructor for this class (or at least, none
+that I'm going to tell you about :-) ResultSet objects are always
+created by the Net::Z3950 module itself, and are returned to the caller
+via the <code>Net::Z3950::Connection</code> class's <code>resultSet()</code> method.</p>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<p>
+</p>
+<h2><a name="size__"><code>size()</code></a></h2>
+<pre>
+ $nrecords = $rs->size();</pre>
+<p>Returns the number of records in the result set <em>$rs</em></p>
+<p>
+</p>
+<h2><a name="subquerycount__"><code>subqueryCount()</code></a></h2>
+<pre>
+ $subquery = $rs->subqueryCount();</pre>
+<p>Returns hit count of subquery terms as a hash reference containing
+(term, count) pairs, if the server returned this information. If the
+information is not available, an undefined value is returned.</p>
+<p>
+</p>
+<h2><a name="present__"><code>present()</code></a></h2>
+<pre>
+ $rs->present($start, $count) or die "failed: $rs->{errcode}\n";</pre>
+<p>Causes any records in the specified range that are not yet in the
+cache to be retrieved from the server. By calling this method before
+retrieving individual records with <code>record()</code>, you avoid sending lots
+of small requests for single records across the network. In
+asynchronous mode, <code>present()</code> just schedules the records for
+retrieval.</p>
+<p>Note that <code>$start</code> is indexed from 1.</p>
+<p>In synchronous mode, returns 1 if the records were successfully
+retrieved, 0 if an error occurred. In asynchronous mode, returns 1 if
+new requests were queued, 0 if all of the requested records had
+already been queued.</p>
+<p>
+</p>
+<h2><a name="record__"><code>record()</code></a></h2>
+<pre>
+ $rec = $rs->record($n);</pre>
+<p>Returns a reference to <em>$n</em>th record in the result set <em>$rs</em>, if the
+content of that record is known. Valid values of <em>$n</em> range from 1
+to the return value of the <code>size()</code> method.</p>
+<p>If the record is not available, an undefined value is returned, and
+diagnostic information made available via <em>$rs</em>'s <code>errcode()</code> and
+<code>addinfo()</code> methods.</p>
+<p>As a special case, when the connection is anychronous, the
+<code>errcode()</code> may be zero, indicating simply that the record has not
+yet been fetched from the server. In this case, the calling code
+should try again later. (How much later? As a rule of thumb, after
+it's done ``something else'', such as request another record or issue
+another search.) This can never happen in synchronous mode.</p>
+<p>
+</p>
+<h2><a name="records__"><code>records()</code></a></h2>
+<pre>
+ @records = $rs->records();
+ foreach $rec (@records) {
+ print $rec->render();
+ }</pre>
+<p>This utility method returns a list of all the records in the result
+set I$<rs>. Because Perl arrays are indexed from zero, the first
+record is <code>$records[0]</code>, the second is <code>$records[1]</code>, <em>etc.</em></p>
+<p>If not all the records associated with <em>$rs</em> have yet been
+transferred from the server, then they need to be transferred at this
+point. This means that the <code>records()</code> method may block, and so is
+not recommended for use in applications that interact with multiple
+servers simultaneously. It does also have the side-effect that
+subsequent invocations of the <code>record()</code> method will always
+immediately return either a legitimate record or a ``real error''
+rather than a ``not yet'' indicator.</p>
+<p>If an error occurs, an empty list is returned. Since this is also
+what's returned when the search had zero hits, well-behaved
+applications will consult <code>$rs-</code>size()> in these circumstances to
+determine which of these two conditions pertains. After an error has
+occurred, details may be obtained via the result set's <code>errcode()</code>
+and <code>addinfo()</code> methods.</p>
+<p>If a non-empty list is returned, then individual elements of that list
+may still be undefined, indicating that corresponding record could not
+be fetched. In order to get more information, it's necessary to
+attempt to fetch the record using the <code>record()</code> method, then consult
+the <code>errcode()</code> and <code>addinfo()</code> methods.</p>
+<p><strong>Unwarranted personal opinion</strong>: all in all, this method is a pleasant
+short-cut for trivial programs to use, but probably carries too many
+caveats to be used extensively in serious applications. You may want to
+take a look at <code>present()</code> and the <code>prefetch</code> option instead.</p>
+<p><strong>AS OF RELEASE 0.31, THIS METHOD IS NOW DEPRECATED.
+PLEASE USE record() INSTEAD.</strong></p>
+<p>
+</p>
+<h2><a name="delete__"><code>delete()</code></a></h2>
+<pre>
+ $ok = $rs->delete();
+ if (!$ok) {
+ print "can't delete: ", $rs->errmsg(), "\n";
+ }</pre>
+<p>Requests the server to delete the result set corresponding to <code>$rs</code>.
+Return non-zero on success, zero on failure.</p>
+<p>
+</p>
+<h2><a name="errcode____addinfo____errmsg__">errcode(), addinfo(), <code>errmsg()</code></a></h2>
+<pre>
+ if (!defined $rs->record($i)) {
+ print "error ", $rs->errcode(), " (", $rs->errmsg(), ")\n";
+ print "additional info: ", $rs->addinfo(), "\n";
+ }</pre>
+<p>When a result set's <code>record()</code> method returns an undefined value,
+indicating an error, it also sets into the result set the BIB-1 error
+code and additional information returned by the server. They can be
+retrieved via the <code>errcode()</code> and <code>addinfo()</code> methods.</p>
+<p>As a convenience, <code>$rs-</code>errmsg()> is equivalent to
+<code>Net::Z3950::errstr($rs-</code>errcode())>.</p>
+<p>
+</p>
+<h2><a name="option__"><code>option()</code></a></h2>
+<pre>
+ $value = $rs->option($type);
+ $value = $rs->option($type, $newval);</pre>
+<p>Returns <em>$rs</em>'s value of the standard option <em>$type</em>, as registered
+in <em>$rs</em> itself, in the connection across which it was created, in
+the manager which controls that connection, or in the global defaults.</p>
+<p>If <em>$newval</em> is specified, then it is set as the new value of that
+option in <em>$rs</em>, and the option's old value is returned.</p>
+<p>
+</p>
+<hr />
+<h1><a name="author">AUTHOR</a></h1>
+<p>Mike Taylor <<a href="mailto:mike at indexdata.com">mike at indexdata.com</a>></p>
+<p>First version Sunday 28th May 2000.</p>
+
+</body>
+
+</html>
Added: packages/libnet-z3950-perl/trunk/doc/Z3950/Tutorial.html
===================================================================
--- packages/libnet-z3950-perl/trunk/doc/Z3950/Tutorial.html 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/doc/Z3950/Tutorial.html 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,757 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Net::Z3950::Tutorial - tutorial for the Net::Z3950 module</title>
+<link rev="made" href="mailto:root at localhost" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#a_very_simple_client">A VERY SIMPLE CLIENT</a></li>
+ <li><a href="#how_it_works">HOW IT WORKS</a></li>
+ <li><a href="#more_complex_behaviour">MORE COMPLEX BEHAVIOUR</a></li>
+ <ul>
+
+ <li><a href="#searching">Searching</a></li>
+ <li><a href="#retrieval">Retrieval</a></li>
+ <li><a href="#scanning">Scanning</a></li>
+ </ul>
+
+ <li><a href="#what_to_do_with_your_records">WHAT TO DO WITH YOUR RECORDS</a></li>
+ <ul>
+
+ <li><a href="#marc_records">MARC RECORDS</a></li>
+ <li><a href="#grs1_records">GRS-1 RECORDS</a></li>
+ </ul>
+
+ <li><a href="#changing_session_parameters">CHANGING SESSION PARAMETERS</a></li>
+ <ul>
+
+ <li><a href="#make_or_find_a_manager">Make or Find a Manager</a></li>
+ <li><a href="#set_the_parameters">Set the Parameters</a></li>
+ </ul>
+
+ <li><a href="#option_inheritance">OPTION INHERITANCE</a></li>
+ <li><a href="#asynchronous_mode">ASYNCHRONOUS MODE</a></li>
+ <li><a href="#now_what">NOW WHAT?</a></li>
+ <li><a href="#author">AUTHOR</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Net::Z3950::Tutorial - tutorial for the Net::Z3950 module</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<p>Apparently, every POD document has to have a SYNOPSIS. So here's one.</p>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p><code>Net::Z3950</code> is a Perl module for writing Z39.50 clients. (If you
+want to write a Z39.50 server, you want the
+<code>Net::Z3950::SimpleServer</code> module.)</p>
+<p>Its goal is to hide all the messy details of the Z39.50 protocol - at
+least by default - while providing access to all of its glorious
+power. Sometimes, this involves revealing the messy details after
+all, but at least this is the programmer's choice. The result is that
+writing Z39.50 clients works the way it should according my favourite
+of the various Perl mottos: ``Simple things should be simple, and
+difficult things should be possible.''</p>
+<p>If you don't know what Z39.50 is, then the best place to find out is
+at
+<a href="http://lcweb.loc.gov/z3950/agency/">http://lcweb.loc.gov/z3950/agency/</a>
+the web site of the Z39.50 Maintenance Agency. Among its many other
+delights, this site contains a complete downloadable soft-copy of the
+standard itself. In briefest summary, Z39.50 is the international
+standard for distributed searching and retrieval.</p>
+<p>
+</p>
+<hr />
+<h1><a name="a_very_simple_client">A VERY SIMPLE CLIENT</a></h1>
+<p>The <code>Net::Z3950</code> distribution includes a couple of sample clients in
+the <code>samples</code> directory. The simplest of them, <code>trivial.pl</code> reads
+as follows:</p>
+<pre>
+ use Net::Z3950;
+ $conn = new Net::Z3950::Connection('indexdata.dk', 210,
+ databaseName => 'gils');
+ $rs = $conn->search('mineral');
+ print "found ", $rs->size(), " records:\n";
+ my $rec = $rs->record(1);
+ print $rec->render();</pre>
+<p>This complete program retrieves from the database called ``gils'' on
+the Z39.50 server on port 210 of <code>indexdata.dk</code> the first record
+matching the search ``mineral'', and renders it in human-readable
+form. Typical output would look like this:</p>
+<pre>
+ 6 fields:
+ (1,1) 1.2.840.10003.13.2
+ (1,14) "2"
+ (2,1) {
+ (1,19) "UTAH EARTHQUAKE EPICENTERS"
+ (3,Acronym) "UUCCSEIS"
+ }
+ (4,52) "UTAH GEOLOGICAL AND MINERAL SURVEY"
+ (4,1) "ESDD0006"
+ (1,16) "198903"</pre>
+<p>
+</p>
+<hr />
+<h1><a name="how_it_works">HOW IT WORKS</a></h1>
+<p>Let's pick the trivial client apart line by line (it won't take long!)</p>
+<pre>
+ use Net::Z3950;</pre>
+<p>This line simply tells Perl to pull in the <code>Net::Z3950</code> module - a
+prerequisite for using types like <code>Net::Z3950::Connection</code>.</p>
+<pre>
+ $conn = new Net::Z3950::Connection('indexdata.dk', 210,
+ databaseName => 'gils');</pre>
+<p>Creates a new connection to the Z39.50 server on port 210 of the host
+<code>indexdata.dk</code>, noting that searches on this connection will default
+to the database called ``gils''. A reference to the new connection is
+stored in <code>$conn</code>.</p>
+<pre>
+ $rs = $conn->search('mineral');</pre>
+<p>Performs a single-word search on the connection referenced by <code>$conn</code>
+(in the previously established default database, ``gils''.) In
+response, the server generates an <em>result set</em>, notionally containing
+all the matching records; a reference to the new connection is stored
+in <code>$rs</code>.</p>
+<pre>
+ print "found ", $rs->size(), " records:\n";</pre>
+<p>Prints the number of records in the new result set <code>$rs</code>.</p>
+<pre>
+ my $rec = $rs->record(1);</pre>
+<p>Fetches from the server the first record in the result set <code>$rs</code>,
+requesting the default record syntax (GRS-1) and the default element
+set (brief, ``b''); a reference to the newly retrieved record is
+stored in <code>$rec</code>.</p>
+<pre>
+ print $rec->render();</pre>
+<p>Prints a human-readable rendition of the record <code>$rec</code>. The exact
+format of the rendition is dependent on issues like the record syntax
+of the record that the server sent.</p>
+<p>
+</p>
+<hr />
+<h1><a name="more_complex_behaviour">MORE COMPLEX BEHAVIOUR</a></h1>
+<p>
+</p>
+<h2><a name="searching">Searching</a></h2>
+<p>Searches may be specified in one of several different syntaxes.
+The default
+syntax is so-called Prefix Query Notation, or PQN, a bespoke format
+invented by Index Data to map simply to the Z39.50 type-1 query
+structure. A second is the Common Command Language (CCL) an
+international standard query language often used in libraries.
+The third is the Common Query Language (CQL) the query language
+used by SRW and SRU.</p>
+<p>CCL queries may be interpreted on the client side and translated into
+a type-1 query which is forwarded to the server; or it may be sent
+``as is'' for the server to interpret as it may. CQL queries may only
+be passed ``as is''.</p>
+<p>The interpretation of the search string may be specified by passing an
+argument of <code>-prefix</code>, <code>-ccl</code>, <code>-ccl2rpn</code> or <code>-cql</code> to the <code>search()</code>
+method before the search string itself, as follows:</p>
+<p><strong>Prefix Queries</strong></p>
+<pre>
+ $rs = $conn->search(-prefix => '@or rock @attr 1=21 mineral');</pre>
+<p>Prefix Query Notation is fully described in section 8.1 (<strong>Query
+Syntax Parsers</strong>) of the Yaz toolkit documentation, <strong>YAZ User's Guide
+and Reference</strong>.</p>
+<p>Briefly, however, keywords begin with an <code>@</code>-sign, and all other
+words are interpreted as search terms. Keywords include the binary
+operators <code>@and</code> and <code>@or</code>, which join together the two operands
+that follow them, and <code>@attr</code>, which introduces a <em>type</em>=<em>value</em>
+expression specifying an attribute to be applied to the following
+term.</p>
+<p>So:</p>
+<ul>
+<li></li>
+<code>fruit</code> searches for the term ``fruit'',
+<p></p>
+<li></li>
+<code>@and fruit fish</code> searches for records containing both ``fruit'' and
+``fish'',
+<p></p>
+<li></li>
+<code>@or fish chicken</code> searches for records containing either ``fish'' or
+``chicken'' (or both),
+<p></p>
+<li></li>
+<code>@and fruit @or fish chicken</code> searches for records containing both
+``fruit'' and at least one of ``fish'' or ``chicken''.
+<p></p>
+<li></li>
+<code>@or rock @attr 1=21 mineral</code> searches for records either containing
+``rock'' or ``mineral'', but with the ``mineral'' search term carrying
+an attribute of type 1, with value 21 (typically interpreted to mean
+that the search term must occur in the ``subject'' field of the
+record.)
+<p></p></ul>
+<p><strong>CCL Queries</strong></p>
+<pre>
+ $rs = $conn->search(-ccl2rpn => 'rock or su=mineral');
+ $rs = $conn->search(-ccl => 'rock or su=mineral');</pre>
+<p>CCL is formally specified in the international standard ISO 8777
+(<strong>Commands for interactive text searching</strong>) and also described in
+section 8.1 (<strong>Query Syntax Parsers</strong>) of the Yaz toolkit
+documentation, <strong>YAZ User's Guide and Reference</strong>.</p>
+<p>Briefly, however, there is a set of well-known keywords including
+<code>and</code>, <code>or</code> and <code>not</code>. Words other than these are interpreted as
+search terms. Operating grouping (precedence) is specified by
+parentheses, and the semantics of a search term may be modified by
+prepending one or more comma-separated qualifiers qualifiers and an
+equals sign.</p>
+<p>So:</p>
+<ul>
+<li></li>
+<code>fruit</code> searches for the term ``fruit'',
+<p></p>
+<li></li>
+<code>fruit and fish</code> searches for records containing both ``fruit'' and
+``fish'',
+<p></p>
+<li></li>
+<code>fish or chicken</code> searches for records containing either ``fish'' or
+``chicken'' (or both),
+<p></p>
+<li></li>
+<code>fruit and (fish or chicken)</code> searches for records containing both
+``fruit'' and at least one of ``fish'' or ``chicken''.
+<p></p>
+<li></li>
+<code>rock or su=mineral</code> searches for records either containing
+``rock'' or ``mineral'', but with the ``mineral'' search term modified
+by the qualifier ``su'' (typically interpreted to mean that the search
+term must occur in the ``subject'' field of the record.)
+<p></p></ul>
+<p>For CCL searches sent directly to the server (query type <code>ccl</code>), the
+exact interpretation of the qualifiers is the server's
+responsibility. For searches compiled on the client side (query side
+<code>ccl2rpn</code>) the interpretation of the qualifiers in terms of type-1
+attributes is determined by the contents of a file called
+<em>### not yet implemented</em>.
+The format of this file is described in the Yaz documentation.</p>
+<p><strong>CQL Queries</strong></p>
+<pre>
+ $rs = $conn->search(-cql => 'au-(kernighan and ritchie)');</pre>
+<p>CQL syntax is very similar to that of CCL.</p>
+<p><strong>Setting Search Defaults</strong></p>
+<p>As an alternative to explicitly specifying the query type when
+invoking the <code>search()</code> method, you can change the connection's
+default query type using its <code>option()</code> method:</p>
+<pre>
+ $conn->option(querytype => 'prefix');
+ $conn->option(querytype => 'ccl');
+ $conn->option(querytype => 'ccl2rpn');</pre>
+<p>The connection's current default query type can be retrieved using
+<code>option()</code> with no ``value'' argument:</p>
+<pre>
+ $qt = $conn->option('querytype');</pre>
+<p>The <code>option()</code> method can be used to set and get numerous other
+defaults described in this document and elsewhere; this method exists
+not only on connections but also on managers (q.v.) and result sets.</p>
+<p>Another important option is <a href="#item_databasename"><code>databaseName</code></a>, whose value specifies
+which database is to be searched.</p>
+<p>
+</p>
+<h2><a name="retrieval">Retrieval</a></h2>
+<p>By default, records are requested from the server one at a time;
+this can be quite slow when retrieving several records. There are two
+ways of improving this. First, the <code>present()</code> method can be used to
+explicitly precharge the cache. Its parameters are a start record and
+record count. In the following example, the <code>present()</code> is optional and
+merely makes the code run faster:</p>
+<pre>
+ $rs->present(11, 5) or die ".....";
+ foreach my $i (11..15) {
+ my $rec = $rs->record($i);
+ ...
+ }</pre>
+<p>The second way is with the <code>prefetch</code> option. Setting this to a
+positive integer makes the <code>record()</code> method fetch the next N
+records and place them in the cache if the the current record
+isn't already there. So the following code would cause two bouts of
+network activity, each retrieving 10 records.</p>
+<pre>
+ $rs->option(prefetch => 10);
+ foreach my $i (1..20) {
+ my $rec = $rs->record($i);
+ ...
+ }</pre>
+<p>In asynchronous mode, <code>present()</code> and <code>prefetch</code> merely cause the
+records to be scheduled for retrieval.</p>
+<p><strong>Element Set</strong></p>
+<p>The default element set is ``b'' (brief). To change this, set the
+result set's <a href="#item_elementsetname"><code>elementSetName</code></a> option:</p>
+<pre>
+ $rs->option(elementSetName => "f");</pre>
+<p><strong>Record Syntax</strong></p>
+<p>The default record syntax preferred by the <code>Net::Z3950</code> module is
+GRS-1 (the One True Record syntax). If, however, you need to ask the
+server for a record using a different record syntax, then the way to
+do this is to set the <a href="#item_preferredrecordsyntax"><code>preferredRecordSyntax</code></a> option of the result
+set from which the record is to be fetched:</p>
+<pre>
+ $rs->option(preferredRecordSyntax => "SUTRS");</pre>
+<p>The record syntaxes which may be requested are listed in the
+<code>Net::Z3950::RecordSyntax</code> enumeration in the file <code>Net/Z3950.pm</code>;
+they include
+<code>Net::Z3950::RecordSyntax::GRS1</code>,
+<code>Net::Z3950::RecordSyntax::SUTRS</code>,
+<code>Net::Z3950::RecordSyntax::USMARC</code>,
+<code>Net::Z3950::RecordSyntax::TEXT_XML</code>,
+<code>Net::Z3950::RecordSyntax::APPLICATION_XML</code>
+and
+<code>Net::Z3950::RecordSyntax::TEXT_HTML</code></p>
+<p>(As always, <code>option()</code> may also be invoked with no ``value''
+parameter to return the current value of the option.)</p>
+<p>
+</p>
+<h2><a name="scanning">Scanning</a></h2>
+<p><strong>### Note to self - write this section!</strong></p>
+<p>
+</p>
+<hr />
+<h1><a name="what_to_do_with_your_records">WHAT TO DO WITH YOUR RECORDS</a></h1>
+<p>Once you've retrieved a record, what can you do with it?</p>
+<p>There are two broad approaches. One is just to display it to the
+user: this can always be done with the <code>render()</code> method, as used in
+the sample code above, whatever the record syntax of the record.</p>
+<p>The more sophisticated approach is to perform appropriate analysis and
+manipulation of the raw record according to the record syntax. The
+raw data is retrieved using the <code>rawdata()</code> method, and the record
+syntax can be determined using the universal <code>isa()</code> method:</p>
+<pre>
+ $raw = $rec->rawdata();
+ if ($rec->isa('Net::Z3950::Record::GRS1')) {
+ process_grs1_record($raw);
+ elsif ($rec->isa('Net::Z3950::Record::USMARC')) {
+ process_marc_record($raw);
+ } # etc.</pre>
+<p>
+</p>
+<h2><a name="marc_records">MARC RECORDS</a></h2>
+<p>For further manipulation of MARC records, we recommend the existing
+MARC module in Ed Summers's directory at CPAN,
+<a href="http://cpan.valueclick.com/authors/id/E/ES/ESUMMERS/">http://cpan.valueclick.com/authors/id/E/ES/ESUMMERS/</a></p>
+<p>
+</p>
+<h2><a name="grs1_records">GRS-1 RECORDS</a></h2>
+<p>The raw data of GRS-1 records in the <code>Net::Z3950</code> module closely
+follows the structure of physcial GRS-1 records - see Appendices REC.5
+(<strong>Generic Record Syntax 1</strong>), TAG (<strong>TagSet Definitions and Schemas</strong>)
+and RET (<strong>Z39.50 Retrieval</strong>) of the standard more details.</p>
+<p>The raw GRS-1 data is intended to be more or less self-describing, but
+here is a summary.</p>
+<ul>
+<li></li>
+The raw data is a reference to an array of elements, each representing
+one of the fields of the record.
+<p></p>
+<li></li>
+Each element is a <code>Net::Z3950::APDU::TaggedElement</code> object. These
+objects support the accessor methods <code>tagType()</code>, <code>tagValue()</code>,
+<code>tagOccurrence()</code> and <code>content()</code>; the first three of these return
+numeric values, or strings in the less common case of string
+tag-values.
+<p></p>
+<li></li>
+The <code>content()</code> of an element is an object of type
+<code>Net::Z3950::ElementData</code>. Its <code>which()</code> method returns a constant
+indicating the type of the content, which may be any of the following:
+<ul>
+<li></li>
+<code>Net::Z3950::ElementData::Numeric</code>
+indicates that the content is a number;
+access it via the
+<code>numeric()</code>
+method.
+<p></p>
+<li></li>
+<code>Net::Z3950::ElementData::String</code>
+indicates that the content is a string of characters;
+access it via the
+<code>string()</code>
+method.
+<p></p>
+<li></li>
+<code>Net::Z3950::ElementData::OID</code>
+indicates that the content is an OID, represented as a string with the
+components separated by periods (``<code>.</code>'');
+access it via the
+<code>oid()</code>
+method.
+<p></p>
+<li></li>
+<code>Net::Z3950::ElementData::Subtree</code>
+is
+a reference to another <code>Net::Z3950::Record::GRS1</code> object, enabling
+arbitrary recursive nesting;
+access it via the
+<code>subtree()</code>
+method.
+<p></p></ul>
+</ul>
+<p>In the future, we plan to take you away from all this by introducing a
+<code>Net::Z3950::Data</code> module which provides a DOM-like interface for
+walking hierarchically structured records independently of their
+record syntax. Keep watchin', kids!</p>
+<p>
+</p>
+<hr />
+<h1><a name="changing_session_parameters">CHANGING SESSION PARAMETERS</a></h1>
+<p>As with customising searching or retrieval behaviour, whole-session
+behaviour is customised by setting options. However, this needs to be
+done before the session is created, because the Z39.50 protocol
+doesn't provide a method for changing (for example) the preferred
+message size of an existing connection.</p>
+<p>In the <code>Net::Z3950</code> module, this is done by creating a <em>manager</em> - a
+controller for one or more connections. Then the manager's options
+can be set; then connections which are opened through the manager use
+the specified values for those options.</p>
+<p>As a matter of fact, <em>every</em> connection is made through a manager.
+If one is not specified in the connection constructor, then the
+``default manager'' is used; it's automatically created the first time
+it's needed, then re-used for any other connections that need it.</p>
+<p>
+</p>
+<h2><a name="make_or_find_a_manager">Make or Find a Manager</a></h2>
+<p>A new manager is created as follows:</p>
+<pre>
+ $mgr = new Net::Z3950::Manager();</pre>
+<p>Once the manager exists, a new connection can be made through it by
+specifying the manager reference as the first argument to the connection
+constructor:</p>
+<pre>
+ $conn = new Net::Z3950::Connection($mgr, 'indexdata.dk', 210);</pre>
+<p>Or equivalently,</p>
+<pre>
+ $conn = $mgr->connect('indexdata.dk', 210);</pre>
+<p>In order to retrieve the manager through which a connection was made,
+whether it was the implicit default manager or not, use the
+<code>manager()</code> method:</p>
+<pre>
+ $mgr = $conn->manager();</pre>
+<p>
+</p>
+<h2><a name="set_the_parameters">Set the Parameters</a></h2>
+<p>There are two ways to set parameters. One we have already seen: the
+<code>option()</code> method can be used to get and set option values for
+managers just as it can for connections and result sets:</p>
+<pre>
+ $pms = $mgr->option('preferredMessageSize');
+ $mgr->option(preferredMessageSize => $pms*2);</pre>
+<p>Alternatively, options may be passed to the manager constructor when
+the manager is first created:</p>
+<pre>
+ $mgr = new Net::Z3950::Manager(
+ preferredMessageSize => 100*1024,
+ maximumRecordSize => 10*1024*1024,
+ preferredRecordSyntax => "GRS-1");</pre>
+<p>This is <em>exactly</em> equivalent to creating a ``vanilla'' manager with
+<code>new Net::Z3950::Manager()</code>, then setting the three options with the
+<code>option()</code> method.</p>
+<p><strong>Message Size Parameters</strong></p>
+<p>The <a href="#item_preferredmessagesize"><code>preferredMessageSize</code></a> and <a href="#item_maximumrecordsize"><code>maximumRecordSize</code></a> parameters can be
+used to specify values of the corresponding parameters which are
+proposed to the server at initialisation time (although the server is
+not bound to honour them.) See sections 3.2.1.1.4
+(<strong>Preferred-message-size and Exceptional-message-size</strong>) and 3.3
+(<strong>Message/Record Size and Segmentation</strong>) of the Z39.50 standard
+itself for details.</p>
+<p>Both options default to one megabyte.</p>
+<p><strong>Implementation Identification</strong></p>
+<p>The <a href="#item_implementationid"><code>implementationId</code></a>, <a href="#item_implementationname"><code>implementationName</code></a> and
+<a href="#item_implementationversion"><code>implementationVersion</code></a> options can be used to control the
+corresponding parameters in initialisation request sent to the server
+to identify the client. The default values are listed below in the
+section <strong>OPTION INHERITANCE</strong>.</p>
+<p><strong>Authentication</strong></p>
+<p>The <a href="#item_user"><code>user</code></a>, <a href="#item_pass"><code>pass</code></a> and <a href="#item_group"><code>group</code></a> options can be specified for a
+manager so that they are passed as identification tokens at
+initialisation time to any connections opened through that manager.
+The three options are interpreted as follows:</p>
+<ul>
+<li></li>
+If <a href="#item_user"><code>user</code></a> is not specified, then authentication is omitted (which is
+more or less the same as ``anonymous'' authentication).
+<p></p>
+<li></li>
+If <a href="#item_user"><code>user</code></a> is specified but not <a href="#item_pass"><code>pass</code></a>, then the value of the
+<a href="#item_user"><code>user</code></a> option is passed as an ``open'' authentication token.
+<p></p>
+<li></li>
+If both <a href="#item_user"><code>user</code></a> and <a href="#item_pass"><code>pass</code></a> are specified, then their values are
+passed in an ``idPass'' authentication structure, together with the
+value of <a href="#item_group"><code>group</code></a> if is it specified.
+<p></p></ul>
+<p>By default, all three options are undefined, so no authentication is
+used.</p>
+<p><strong>Character set and language negotiation</strong></p>
+<p>The <a href="#item_charset"><code>charset</code></a> and <a href="#item_language"><code>language</code></a> options can be used to negotiate the
+character set and language to be used for connections opened through
+that manager. If these options are set, they are passed to the server
+in a character-negotition otherInfo package attached to the
+initialisation request.</p>
+<p>
+</p>
+<hr />
+<h1><a name="option_inheritance">OPTION INHERITANCE</a></h1>
+<p>The values of options are inherited from managers to connections,
+result sets and finally to records.</p>
+<p>This means that when a record is asked for an option value (whether by
+an application invoking its <code>option()</code> method, or by code inside the
+module that needs to know how to behave), that value is looked for
+first in the record's own table of options; then, if it's not
+specified there, in the options of the result set from which the
+record was retrieved; then if it's not specified there, in those of
+the connection across which the result set was found; and finally, if
+not specified there either, in the options for the manager through
+which the connection was created.</p>
+<p>Similarly, option values requested from a result set are looked up (if
+not specified in the result set itself) in the connection, then the
+manager; and values requested from a connection fall back to its
+manager.</p>
+<p>This is why it made sense in an earlier example (see the section <strong>Set
+the Parameters</strong>) to specify a value for the <a href="#item_preferredrecordsyntax"><code>preferredRecordSyntax</code></a>
+option when creating a manager: the result of this is that, unless
+overridden, it will be the preferred record syntax when any record is
+retrieved from any result set retrieved from any connection created
+through that manager. In effect, it establishes a global default.
+Alternatively, one might specify different defaults on two different
+connections.</p>
+<p>In all cases, if the manager doesn't have a value for the requested
+option, then a hard-wired default is used. The defaults are as
+follows. (Please excuse the execrable formatting - that's what
+<code>pod2html</code> does, and there's no sensible way around it.)</p>
+<dl>
+<dt><strong><a name="item_die_handler"><code>die_handler</code></a></strong><br />
+</dt>
+<dd>
+<code>undef</code>
+A function to invoke if <code>die()</code> is called within the main event loop.
+</dd>
+<p></p>
+<dt><strong><a name="item_timeout"><code>timeout</code></a></strong><br />
+</dt>
+<dd>
+<code>undef</code>
+The maximum number of seconds a manager will wait when its <code>wait()</code>
+method is called. If the timeout elapses, <code>wait()</code> returns an
+undefined value. <strong>Can not be set on a per-connection basis.</strong>
+</dd>
+<p></p>
+<dt><strong><a name="item_async"><code>async</code></a></strong><br />
+</dt>
+<dd>
+<code>0</code>
+(Determines whether a given connection is in asynchronous mode.)
+</dd>
+<p></p>
+<dt><strong><a name="item_preferredmessagesize"><code>preferredMessageSize</code></a></strong><br />
+</dt>
+<dd>
+<code>1024*1024</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_maximumrecordsize"><code>maximumRecordSize</code></a></strong><br />
+</dt>
+<dd>
+<code>1024*1024</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_user"><code>user</code></a></strong><br />
+</dt>
+<dd>
+<code>undef</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_pass"><code>pass</code></a></strong><br />
+</dt>
+<dd>
+<code>undef</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_group"><code>group</code></a></strong><br />
+</dt>
+<dd>
+<code>undef</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_implementationid"><code>implementationId</code></a></strong><br />
+</dt>
+<dd>
+<code>'Mike Taylor (id=169)'</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_implementationname"><code>implementationName</code></a></strong><br />
+</dt>
+<dd>
+<code>'Net::Z3950.pm (Perl)'</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_implementationversion"><code>implementationVersion</code></a></strong><br />
+</dt>
+<dd>
+<code>$Net::Z3950::VERSION</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_charset"><code>charset</code></a></strong><br />
+</dt>
+<dd>
+<code>undef</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_language"><code>language</code></a></strong><br />
+</dt>
+<dd>
+<code>undef</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_querytype"><code>querytype</code></a></strong><br />
+</dt>
+<dd>
+<code>'prefix'</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_databasename"><code>databaseName</code></a></strong><br />
+</dt>
+<dd>
+<code>'Default'</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_smallsetupperbound"><code>smallSetUpperBound</code></a></strong><br />
+</dt>
+<dd>
+<code>0</code>
+(This and the next four options provide flexible control for run-time
+details such as what record syntax to use when returning records. See
+sections
+3.2.2.1.4 (<strong>Small-set-element-set-names and
+Medium-set-element-set-names</strong>)
+and
+3.2.2.1.6 (<strong>Small-set-upper-bound, Large-set-lower-bound, and
+Medium-set-present-number</strong>)
+of the Z39.50 standard itself for details.)
+</dd>
+<p></p>
+<dt><strong><a name="item_largesetlowerbound"><code>largeSetLowerBound</code></a></strong><br />
+</dt>
+<dd>
+<code>1</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_mediumsetpresentnumber"><code>mediumSetPresentNumber</code></a></strong><br />
+</dt>
+<dd>
+<code>0</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_smallsetelementsetname"><code>smallSetElementSetName</code></a></strong><br />
+</dt>
+<dd>
+<code>'f'</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_mediumsetelementsetname"><code>mediumSetElementSetName</code></a></strong><br />
+</dt>
+<dd>
+<code>'b'</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_preferredrecordsyntax"><code>preferredRecordSyntax</code></a></strong><br />
+</dt>
+<dd>
+<code>'GRS-1'</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_responseposition"><code>responsePosition</code></a></strong><br />
+</dt>
+<dd>
+<code>1</code>
+(Indicates the one-based position of the start term in the set of
+terms returned from a scan.)
+</dd>
+<p></p>
+<dt><strong><a name="item_stepsize"><code>stepSize</code></a></strong><br />
+</dt>
+<dd>
+<code>0</code>
+(Indicates the number of terms between each of the terms returned from
+a scan.)
+</dd>
+<p></p>
+<dt><strong><a name="item_numberofentries"><code>numberOfEntries</code></a></strong><br />
+</dt>
+<dd>
+<code>20</code>
+(Indicates the number of terms to return from a scan.)
+</dd>
+<p></p>
+<dt><strong><a name="item_elementsetname"><code>elementSetName</code></a></strong><br />
+</dt>
+<dd>
+<code>'b'</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_namedresultsets"><code>namedResultSets</code></a></strong><br />
+</dt>
+<dd>
+<code>1</code> indicating boolean true. This option tells the client to use a
+new result set name for each new result set generated, so that old
+<code>ResultSet</code> objects remain valid. For the benefit of old, broken
+servers, this option may be set to 0, indicating that same result-set
+name, <code>default</code>, should be used for each search, so that each search
+invalidates all existing <code>ResultSet</code>s.
+</dd>
+<p></p></dl>
+<p>Any other option's value is undefined.</p>
+<p>
+</p>
+<hr />
+<h1><a name="asynchronous_mode">ASYNCHRONOUS MODE</a></h1>
+<p>I don't propose to discuss this at the moment, since I think it's more
+important to get the Tutorial out there with the synchronous stuff in
+place than to write the asynchronous stuff. I'll do it soon, honest.
+In the mean time, let me be clear: the asynchronous code itself is
+done and works (the synchronous interface is merely a thin layer on
+top of it) - it's only the <em>documentation</em> that's not yet here.</p>
+<p><strong>### Note to self - write this section!</strong></p>
+<p>
+</p>
+<hr />
+<h1><a name="now_what">NOW WHAT?</a></h1>
+<p>This tutorial is only an overview of what can be done with the
+<code>Net::Z3950</code> module. If you need more information that it provides,
+then you need to read the more technical documentation on the
+individual classes that make up the module -
+<code>Net::Z3950</code> itself,
+<code>Net::Z3950::Manager</code>,
+<code>Net::Z3950::Connection</code>,
+<code>Net::Z3950::ResultSet</code> and
+<code>Net::Z3950::Record</code>.</p>
+<p>
+</p>
+<hr />
+<h1><a name="author">AUTHOR</a></h1>
+<p>Mike Taylor <<a href="mailto:mike at indexdata.com">mike at indexdata.com</a>></p>
+<p>First version Sunday 28th January 2001.</p>
+
+</body>
+
+</html>
Added: packages/libnet-z3950-perl/trunk/doc/Z3950/style.css
===================================================================
--- packages/libnet-z3950-perl/trunk/doc/Z3950/style.css 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/doc/Z3950/style.css 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,9 @@
+/*
+ * style.css -- HTML style-sheet for Net::Z3950 documentation
+ * $Header: /home/cvsroot/NetZ3950/doc/style.css,v 1.2 2001/10/19 15:40:25 mike Exp $
+ */
+body { color: #000040; background: white }
+h1 { color: #ffffa0; background: #a00000; margin-top: 20px;
+ padding: 5px 10px; border: 1px transparent }
+h2,h3,h4,h5,h6 { color: #600000 }
+.warning { color: #ff0000; background: #ffff80 }
Added: packages/libnet-z3950-perl/trunk/doc/Z3950.html
===================================================================
--- packages/libnet-z3950-perl/trunk/doc/Z3950.html 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/doc/Z3950.html 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,150 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Net::Z3950 - Perl extension for talking to Z39.50 servers.</title>
+<link rev="made" href="mailto:root at localhost" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#asynchronous_synopsis">ASYNCHRONOUS SYNOPSIS</a></li>
+ <li><a href="#functions">FUNCTIONS</a></li>
+ <ul>
+
+ <li><a href="#errstr__"><code>errstr()</code></a></li>
+ <li><a href="#opstr__"><code>opstr()</code></a></li>
+ </ul>
+
+ <li><a href="#author">AUTHOR</a></li>
+ <li><a href="#see_also">SEE ALSO</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Net::Z3950 - Perl extension for talking to Z39.50 servers.</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<p>(This code blocks in reads: see below for sample non-blocking code
+which allows multiple servers to be searched in parallel.)</p>
+<pre>
+ use Net::Z3950;</pre>
+<pre>
+ $conn = new Net::Z3950::Connection('server.host.name', 210)
+ or die $!;
+ $rs = $conn->search('au=kernighan or su=unix')
+ or die $conn->errmsg();</pre>
+<pre>
+ my $n = $rs->size();
+ print "found $n records:\n";
+ foreach $i (1..$n) {
+ $rec = $rs->record($i) or die $rs->errmsg();
+ print $rec->render();
+ }</pre>
+<pre>
+ $conn->close();</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>This module provides a Perl interface to the Z39.50 information
+retrieval protocol (aka. ISO 23950), a mature and powerful protocol
+used in application domains as diverse as bibliographic information,
+geo-spatial mapping, museums and other cultural heritage information,
+and structured vocabulary navigation.</p>
+<p><code>Net::Z3950.pm</code> is an implementation of the Perl binding for ZOOM, the
+Z39.50 Objct Orientation Model. Bindings for the same abstract API
+are, or will be, available in other languages including C, C++, Java
+and Tcl.</p>
+<p>Two basic approaches are possible to building clients with this
+module:</p>
+<ul>
+<li></li>
+The simple synchronous approach considers blocking reads acceptable, and
+therefore allows a straightforward style of imperative programming.
+This approach is suitable for clients which only talk to one server at
+a time, and is exemplified by the code in the SYNOPSIS section above.
+<p></p>
+<li></li>
+The more complex asynchronous approach, appropriate for clients which
+multiplex simultaneous connections, requires a slightly less familiar
+event-driven programming style, as exemplified in the ASYNCHRONOUS
+SYNOPSIS section below.
+<p></p></ul>
+<p>(The simpler synchronous interface functions are implemented as a thin
+layer on top of the asynchronous functions.)</p>
+<p>
+</p>
+<hr />
+<h1><a name="asynchronous_synopsis">ASYNCHRONOUS SYNOPSIS</a></h1>
+<p>(This code does not block in reads, and so is suitable for broadcast
+clients which search multiple servers simultaneously: see above for
+simpler sample code that blocks in reads.)</p>
+<p><em>### To be written</em></p>
+<p>
+</p>
+<hr />
+<h1><a name="functions">FUNCTIONS</a></h1>
+<p>The <code>Net::Z3950</code> module itself provides very few functions: most of the
+functionality is provided by the daughter modules included by <code>Net::Z3950</code>
+- <code>Net::Z3950::Manager</code>, <code>Net::Z3950::Connection</code>, <em>etc.</em></p>
+<p>
+</p>
+<h2><a name="errstr__"><code>errstr()</code></a></h2>
+<pre>
+ $errcode = $conn->errcode();
+ $errmsg = Net::Z3950::errmsg($errcode);
+ print "error $errcode ($errmsg)\n";</pre>
+<p>Returns an English-language string describing the error indicated by
+the Z39.50 BIB-1 diagnostic error code <em>$errcode</em>.</p>
+<p>
+</p>
+<h2><a name="opstr__"><code>opstr()</code></a></h2>
+<pre>
+ $str = Net::Z3950::opstr($conn->errop());
+ print "error occurred in $str\n";</pre>
+<p>Returns an English-language string describing the operation indicated
+by the argument, which must be one of the <code>Net::Z3950::Op::*</code> constants
+described in the documentation for the <code>Net::Z3950::Connection</code> class's
+<code>op()</code> method.</p>
+<p>
+</p>
+<hr />
+<h1><a name="author">AUTHOR</a></h1>
+<p>Mike Taylor <<a href="mailto:mike at indexdata.com">mike at indexdata.com</a>></p>
+<p>First version Tuesday 23rd May 2000.</p>
+<p>
+</p>
+<hr />
+<h1><a name="see_also">SEE ALSO</a></h1>
+<p>The ZOOM API for Z39.50, of which this is an implementation, is fully
+specified at
+<a href="http://zoom.z3950.org">http://zoom.z3950.org</a>
+where links to other implementations may also be found.</p>
+<p>This module is built on Index Data's Yaz (Yet Another Z39.50) toolkit,
+which is freely available at
+<a href="http://indexdata.dk/yaz/">http://indexdata.dk/yaz/</a></p>
+<p>Index Data also provide a variety of other useful Z39.50 software
+including the free server/database Zebra, the commercial
+server/database Z'mbol, a Tcl interface to Z39.50 called Ir/Tcl, and a
+free web-to-Z39.50 gateway called Zap. See their home page at
+<a href="http://indexdata.dk/">http://indexdata.dk/</a></p>
+<p>The best source of information about Z39.50 itself is the official
+Mainenance Agency at
+<a href="http://lcweb.loc.gov/z3950/agency/">http://lcweb.loc.gov/z3950/agency/</a></p>
+
+</body>
+
+</html>
Added: packages/libnet-z3950-perl/trunk/doc/html/APDU.html
===================================================================
--- packages/libnet-z3950-perl/trunk/doc/html/APDU.html 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/doc/html/APDU.html 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,448 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Net::Z3950::APDU - Read-only objects representing decoded Z39.50 APDUs</title>
+<link rev="made" href="mailto:root at localhost" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#subclasses">SUBCLASSES</a></li>
+ <ul>
+
+ <li><a href="#net__z3950__apdu__initresponse">Net::Z3950::APDU::InitResponse</a></li>
+ <li><a href="#net__z3950__apdu__searchresponse">Net::Z3950::APDU::SearchResponse</a></li>
+ <li><a href="#net__z3950__apdu__scanresponse">Net::Z3950::APDU::ScanResponse</a></li>
+ <li><a href="#net__z3950__apdu__presentresponse">Net::Z3950::APDU::PresentResponse</a></li>
+ <li><a href="#net__z3950__apdu__deletersresponse">Net::Z3950::APDU::DeleteRSResponse</a></li>
+ <li><a href="#net__z3950__apdu__close">Net::Z3950::APDU::Close</a></li>
+ <li><a href="#net__z3950__apdu__nameplusrecordlist">Net::Z3950::APDU::NamePlusRecordList</a></li>
+ <li><a href="#net__z3950__apdu__nameplusrecord">Net::Z3950::APDU::NamePlusRecord</a></li>
+ <li><a href="#net__z3950__apdu__sutrs__net__z3950__apdu__usmarc__net__z3950__apdu__ukmarc__net__z3950__apdu__normarc__net__z3950__apdu__librismarc__net__z3950__apdu__danmarc__net__z3950__apdu__unimarc__net__z3950__apdu__mab">Net::Z3950::APDU::SUTRS, Net::Z3950::APDU::USMARC, Net::Z3950::APDU::UKMARC, Net::Z3950::APDU::NORMARC, Net::Z3950::APDU::LIBRISMARC, Net::Z3950::APDU::DANMARC, Net::Z3950::APDU::UNIMARC, Net::Z3950::APDU::MAB</a></li>
+ <li><a href="#net__z3950__apdu__taggedelement_">Net::Z3950::APDU::TaggedElement;</a></li>
+ <li><a href="#net__z3950__apdu__elementdata">Net::Z3950::APDU::ElementData</a></li>
+ <li><a href="#net__z3950__apdu__holdingsdata">Net::Z3950::APDU::HoldingsData</a></li>
+ <li><a href="#net__z3950__apdu__holdingsandcirc">Net::Z3950::APDU::HoldingsAndCirc</a></li>
+ <li><a href="#net__z3950__apdu__volumes">Net::Z3950::APDU::Volumes</a></li>
+ <li><a href="#net__z3950__apdu__holdingsandcirc">Net::Z3950::APDU::HoldingsAndCirc</a></li>
+ <li><a href="#net__z3950__apdu__circulationdata">Net::Z3950::APDU::CirculationData</a></li>
+ <li><a href="#net__z3950__apdu__holdingsandcirc">Net::Z3950::APDU::HoldingsAndCirc</a></li>
+ <li><a href="#net__z3950__apdu__diagrecs">Net::Z3950::APDU::DiagRecs</a></li>
+ <li><a href="#net__z3950__apdu__defaultdiagformat_">Net::Z3950::APDU::DefaultDiagFormat;</a></li>
+ <li><a href="#net__z3950__apdu__oid">Net::Z3950::APDU::OID</a></li>
+ <li><a href="#net__z3950__apdu__listentries">Net::Z3950::APDU::ListEntries</a></li>
+ <li><a href="#net__z3950__apdu__entry">Net::Z3950::APDU::Entry</a></li>
+ <li><a href="#net__z3950__apdu__terminfo">Net::Z3950::APDU::TermInfo</a></li>
+ <li><a href="#net__z3950__apdu__term">Net::Z3950::APDU::Term</a></li>
+ <li><a href="#net__z3950__apdu__otherinformation">Net::Z3950::APDU::OtherInformation</a></li>
+ <li><a href="#net__z3950__apdu__otherinformationunit">Net::Z3950::APDU::OtherInformationUnit</a></li>
+ <li><a href="#net__z3950__apdu__searchinforeport">Net::Z3950::APDU::SearchInfoReport</a></li>
+ <li><a href="#net__z3950__apdu__searchinforeport_s">Net::Z3950::APDU::SearchInfoReport_s</a></li>
+ <li><a href="#net__z3950__apdu__queryexpression">Net::Z3950::APDU::QueryExpression</a></li>
+ <li><a href="#net__z3950__apdu__queryexpressionterm">Net::Z3950::APDU::QueryExpressionTerm</a></li>
+ </ul>
+
+ <li><a href="#author">AUTHOR</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Net::Z3950::APDU - Read-only objects representing decoded Z39.50 APDUs</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<p><em>You probably shouldn't be reading this!</em></p>
+<pre>
+ package Net::Z3950::APDU::SomeSpecificSortOfAPDU;
+ use Net::Z3950::APDU;
+ @ISA = qw(Net::Z3950::APDU);
+ @FIELDS = qw(names of APDU fields);</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>This class provides a trivial base for the various read-only APDUs
+implemented as a part of the Net::Z3950 module. Its role is simply to
+supply named methods providing read-only access to the same-named
+fields. The set of fields is specified by the derived class's
+package-global <code>@FIELDS</code> array.</p>
+<p><em>You don't need to understand or use this class in order to use the
+Net::Z3950 module. It's purely an implementation detail. In fact, I
+probably should never even have written this documentation. Forget I
+said anything. Go and read the next section.</em></p>
+<p>
+</p>
+<hr />
+<h1><a name="subclasses">SUBCLASSES</a></h1>
+<p>The following classes are all trivial derivations of <code>Net::Z3950::APDU</code>,
+and represent specific types of APDU. Each such class is
+characterised by the set of data-access methods it supplies: these are
+listed below.</p>
+<p>Each method takes no arguments, and returns the information implied by
+its name. See the relevant sections of the Z39.50 Standard for
+information on the interpretation of this information - for example,
+section 3.2.1 (Initialization Facility) describes the elements of the
+<code>Net::Z3950::APDU::InitResponse</code> class.</p>
+<p><em>Actually, you don't need to understand or use any of these classes
+either: they're used internally in the implementation, so this
+documentation is provided as a service to those who will further
+develop this module in the future.</em></p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__initresponse">Net::Z3950::APDU::InitResponse</a></h2>
+<pre>
+ referenceId()
+ preferredMessageSize()
+ maximumRecordSize()
+ result()
+ implementationId()
+ implementationName()
+ implementationVersion()</pre>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__searchresponse">Net::Z3950::APDU::SearchResponse</a></h2>
+<pre>
+ referenceId()
+ resultCount()
+ numberOfRecordsReturned()
+ nextResultSetPosition()
+ searchStatus()
+ resultSetStatus()
+ presentStatus()
+ records()
+ additionalSearchInfo()</pre>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__scanresponse">Net::Z3950::APDU::ScanResponse</a></h2>
+<pre>
+ referenceId()
+ stepSize()
+ scanStatus()
+ numberOfEntriesReturned()
+ positionOfTerm()
+ entries()
+ diag()</pre>
+<p>The <code>diag()</code> method should be consulted when <code>scanStatus()</code> returns
+6, indicating failure; otherwise, <code>entries()</code> may be consulted.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__presentresponse">Net::Z3950::APDU::PresentResponse</a></h2>
+<pre>
+ referenceId()
+ numberOfRecordsReturned()
+ nextResultSetPosition()
+ presentStatus()
+ records()</pre>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__deletersresponse">Net::Z3950::APDU::DeleteRSResponse</a></h2>
+<pre>
+ referenceId()
+ deleteOperationStatus()</pre>
+<p>(We don't bother to decode the rest of this APDU at the moment, since
+I bet everyone calls <code>Net::Z3950::ResultSet::delete()</code> in void
+context. If anyone wants more information out of it, we can wire it
+through.)</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__close">Net::Z3950::APDU::Close</a></h2>
+<pre>
+ referenceId()
+ closeReason()
+ diagnosticInformation()</pre>
+<p>In addition, this class provides a method of no arguments,
+<code>as_text()</code>, which returns a human-readable string describing the
+reason for the close.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__nameplusrecordlist">Net::Z3950::APDU::NamePlusRecordList</a></h2>
+<p>No methods - just treat as a reference to an array of
+<code>Net::Z3950::APDU::NamePlusRecord</code></p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__nameplusrecord">Net::Z3950::APDU::NamePlusRecord</a></h2>
+<pre>
+ databaseName()
+ which()
+ databaseRecord()
+ surrogateDiagnostic()
+ startingFragment()
+ intermediateFragment()
+ finalFragment()</pre>
+<p>Only one of the last five methods will return anything - you can find
+out which one by inspecting the return value of the <code>which()</code> method,
+which always takes one of the following values:</p>
+<ul>
+<li></li>
+Net::Z3950::NamePlusRecord::DatabaseRecord
+<p></p>
+<li></li>
+Net::Z3950::NamePlusRecord::SurrogateDiagnostic
+<p></p>
+<li></li>
+Net::Z3950::NamePlusRecord::StartingFragment
+<p></p>
+<li></li>
+Net::Z3950::NamePlusRecord::IntermediateFragment
+<p></p>
+<li></li>
+Net::Z3950::NamePlusRecord::FinalFragment
+<p></p></ul>
+<p>When <code>which()</code> is <code>Net::Z3950::NamePlusRecord::DatabaseRecord</code>, the
+object returned from the <code>databaseRecord()</code> method will be a decoded
+Z39.50 EXTERNAL. Its type may be any of the following (and may be
+tested using <code>$rec->isa('Net::Z3950::Record::Whatever')</code> if necessary.)</p>
+<ul>
+<li></li>
+Net::Z3950::Record::SUTRS
+<p></p>
+<li></li>
+Net::Z3950::Record::GRS1
+<p></p>
+<li></li>
+Net::Z3950::Record::USMARC and
+similarly, Net::Z3950::Record::UKMARC, Net::Z3950::Record::NORMARC, <em>etc</em>.
+<p></p>
+<li></li>
+Net::Z3950::Record::XML
+<p></p>
+<li></li>
+Net::Z3950::Record::HTML
+<p></p>
+<li></li>
+Net::Z3950::Record::OPAC
+<p><em>### others, not yet supported</em></p>
+<p></p></ul>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__sutrs__net__z3950__apdu__usmarc__net__z3950__apdu__ukmarc__net__z3950__apdu__normarc__net__z3950__apdu__librismarc__net__z3950__apdu__danmarc__net__z3950__apdu__unimarc__net__z3950__apdu__mab">Net::Z3950::APDU::SUTRS, Net::Z3950::APDU::USMARC, Net::Z3950::APDU::UKMARC, Net::Z3950::APDU::NORMARC, Net::Z3950::APDU::LIBRISMARC, Net::Z3950::APDU::DANMARC, Net::Z3950::APDU::UNIMARC, Net::Z3950::APDU::MAB</a></h2>
+<p>No methods - just treat as an opaque chunk of data.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__taggedelement_">Net::Z3950::APDU::TaggedElement;</a></h2>
+<pre>
+ tagType()
+ tagValue()
+ tagOccurrence()
+ content()</pre>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__elementdata">Net::Z3950::APDU::ElementData</a></h2>
+<pre>
+ which()
+ numeric()
+ string()
+ oid()
+ subtree()</pre>
+<p>Only one of the last four methods will return anything - you can find
+out which one by inspecting the return value of the <code>which()</code> method,
+which always takes one of the following values:</p>
+<ul>
+<li></li>
+Net::Z3950::ElementData::Numeric
+<p></p>
+<li></li>
+Net::Z3950::ElementData::String
+<p></p>
+<li></li>
+Net::Z3950::ElementData::OID
+<p></p>
+<li></li>
+Net::Z3950::ElementData::Subtree
+<p></p>
+<li></li>
+<em>### others, not yet supported</em>
+<p></p></ul>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__holdingsdata">Net::Z3950::APDU::HoldingsData</a></h2>
+<p>No methods - just treat as a reference to an array of objects, where
+each object is either an MARC holdings record (of type
+<code>Net::Z3950::Record::USMARC</code> or similar) or a
+<code>Net::Z3950::APDU::HoldingsAndCirc</code></p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__holdingsandcirc">Net::Z3950::APDU::HoldingsAndCirc</a></h2>
+<pre>
+ typeOfRecord()
+ encodingLevel()
+ format()
+ receiptAcqStatus()
+ generalRetention()
+ completeness()
+ dateOfReport()
+ nucCode()
+ localLocation()
+ shelvingLocation()
+ callNumber()
+ shelvingData()
+ copyNumber()
+ publicNote()
+ reproductionNote()
+ termsUseRepro()
+ enumAndChron()
+ volumes()
+ circulationData()</pre>
+<p>All but the last two of these have string values, although not
+necessarily human-readable strings. <code>volumes()</code> returns a
+<code>Net::Z3950::APDU::Volumes</code> object (note the plural in the
+type-name), and <code>circulationData()</code> a
+<code>Net::Z3950::APDU::CirculationData</code>.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__volumes">Net::Z3950::APDU::Volumes</a></h2>
+<p>No methods - just treat as a reference to an array of
+<code>Net::Z3950::APDU::Volume</code>
+objects.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__holdingsandcirc">Net::Z3950::APDU::HoldingsAndCirc</a></h2>
+<pre>
+ enumeration()
+ chronology()
+ enumAndChron()</pre>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__circulationdata">Net::Z3950::APDU::CirculationData</a></h2>
+<p>No methods - just treat as a reference to an array of
+<code>Net::Z3950::APDU::CircRecord</code>
+objects.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__holdingsandcirc">Net::Z3950::APDU::HoldingsAndCirc</a></h2>
+<pre>
+ availableNow()
+ availablityDate()
+ availableThru()
+ restrictions()
+ itemId()
+ renewable()
+ onHold()
+ enumAndChron()
+ midspine()
+ temporaryLocation()</pre>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__diagrecs">Net::Z3950::APDU::DiagRecs</a></h2>
+<p>No methods - just treat as a reference to an array of object
+references. The objects will typically be of class
+<code>Net::Z3950::APDU::DefaultDiagFormat</code>, but careful callers will check
+this, since any kind of EXTERNAL may be provided instead.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__defaultdiagformat_">Net::Z3950::APDU::DefaultDiagFormat;</a></h2>
+<pre>
+ diagnosticSetId()
+ condition()
+ addinfo()</pre>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__oid">Net::Z3950::APDU::OID</a></h2>
+<p><strong>No longer exists.</strong>
+Previously this class had no methods - calling code just treated it
+as a reference to an array of integers. However, since the only thing
+anyone (including <code>Net::Z3950::Record::GRS1::render()</code>)
+ever did with it was smush it up into a string with</p>
+<pre>
+ join('.', @$oidRef)</pre>
+<p>we now just return the dot-separated OID string
+<em>not blessed into any class</em>
+(because scalars can't be blessed - only <em>references</em> to scalars,
+and we don't want the extra useless level of indirection).</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__listentries">Net::Z3950::APDU::ListEntries</a></h2>
+<p>No methods - just treat as a reference to an array of
+<code>Net::Z3950::APDU::Entry</code></p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__entry">Net::Z3950::APDU::Entry</a></h2>
+<pre>
+ termInfo()
+ surrogateDiagnostic()</pre>
+<p>Usually, <code>termInfo()</code> returns a scanned term. When it returns an
+undefined value, consult <surrogateDiagnostic()> to find out why.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__terminfo">Net::Z3950::APDU::TermInfo</a></h2>
+<pre>
+ term()
+ globalOccurrences()</pre>
+<p><em>### Lots more to come here, including displayTerm</em></p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__term">Net::Z3950::APDU::Term</a></h2>
+<pre>
+ general()
+ numeric()
+ characterString()
+ oid()
+ dateTime()
+ external()
+ integerAndUnit()
+ null()</pre>
+<p>At present only ``general'' terms are supported. The value of such a
+term may be obtained by calling <general()>. Terms of other types can
+not be obtained.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__otherinformation">Net::Z3950::APDU::OtherInformation</a></h2>
+<p>No methods - just treat as a reference to an array of
+<code>Net::Z3950::APDU::OtherInformationUnit</code></p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__otherinformationunit">Net::Z3950::APDU::OtherInformationUnit</a></h2>
+<pre>
+ which()
+ characterInfo()
+ binaryInfo()
+ externallyDefinedInfo
+ oid()</pre>
+<p>At present only ``externallyDefinedInfo'' units are supported.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__searchinforeport">Net::Z3950::APDU::SearchInfoReport</a></h2>
+<p>No methods - just treat as a reference to an array of
+<code>Net::Z3950::APDU::SearchInfoReport_s</code></p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__searchinforeport_s">Net::Z3950::APDU::SearchInfoReport_s</a></h2>
+<pre>
+ fullQuery()
+ subqueryExpression()
+ subqueryCount()</pre>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__queryexpression">Net::Z3950::APDU::QueryExpression</a></h2>
+<pre>
+ which()
+ term()
+ query()</pre>
+<p>At present only ``term'' query expressions are supported.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__queryexpressionterm">Net::Z3950::APDU::QueryExpressionTerm</a></h2>
+<pre>
+ queryTerm()</pre>
+<p>
+</p>
+<hr />
+<h1><a name="author">AUTHOR</a></h1>
+<p>Mike Taylor <<a href="mailto:mike at indexdata.com">mike at indexdata.com</a>></p>
+<p>First version Saturday 27th May 2000.</p>
+
+</body>
+
+</html>
Added: packages/libnet-z3950-perl/trunk/doc/html/Connection.html
===================================================================
--- packages/libnet-z3950-perl/trunk/doc/html/Connection.html 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/doc/html/Connection.html 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,358 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Net::Z3950::Connection - Connection to a Z39.50 server, with request queue</title>
+<link rev="made" href="mailto:root at localhost" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#methods">METHODS</a></li>
+ <ul>
+
+ <li><a href="#new__"><code>new()</code></a></li>
+ <li><a href="#option__"><code>option()</code></a></li>
+ <li><a href="#manager__"><code>manager()</code></a></li>
+ <li><a href="#startsearch__"><code>startSearch()</code></a></li>
+ <li><a href="#startscan__"><code>startScan()</code></a></li>
+ <li><a href="#search__"><code>search()</code></a></li>
+ <li><a href="#scan__"><code>scan()</code></a></li>
+ <li><a href="#op__"><code>op()</code></a></li>
+ <li><a href="#errcode____addinfo____errop____errmsg__">errcode(), addinfo(), errop(), <code>errmsg()</code></a></li>
+ <li><a href="#initresponse__"><code>initResponse()</code></a></li>
+ <li><a href="#searchresponse____resultset__">searchResponse(), <code>resultSet()</code></a></li>
+ <li><a href="#scanresponse____scanset__">scanResponse(), <code>scanSet()</code></a></li>
+ <li><a href="#resultsets__"><code>resultSets()</code></a></li>
+ <li><a href="#name__"><code>name()</code></a></li>
+ <li><a href="#close__"><code>close()</code></a></li>
+ </ul>
+
+ <li><a href="#author">AUTHOR</a></li>
+ <li><a href="#see_also">SEE ALSO</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Net::Z3950::Connection - Connection to a Z39.50 server, with request queue</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ $conn = new Net::Z3950::Connection($hostname, $port);
+ $rs = $conn->search('au=kernighan and su=unix');
+ $sr = $conn->scan('au=kernighan and su=unix');
+ # or
+ $mgr = $conn->manager();
+ $conn = $mgr->wait();
+ if ($mgr->failed()) {
+ die "error " . $conn->errcode() .
+ "( " . $conn->addinfo() . ")" .
+ " in " . Net::Z3950::opstr($conn->errop());
+ }</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>A connection object represents an established connection to a
+particular server on a particular port, together with options such as
+the default database in which to search. It maintains a queue of
+outstanding requests (searches executed against it, fetches executed
+against result sets instantiated against it) <em>etc.</em></p>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<p>
+</p>
+<h2><a name="new__"><code>new()</code></a></h2>
+<pre>
+ $conn = new Net::Z3950::Connection($mgr, $host, $port);
+ $conn = new Net::Z3950::Connection($host, $port);
+ $conn = new Net::Z3950::Connection($mgr, "unix", $path);
+ $conn = new Net::Z3950::Connection("unix", $path);</pre>
+<p>Creates and returns a new connection, under the control of the manager
+<em>$mgr</em>, to the server on the specified <em>$host</em> and <em>$port</em>. If the
+<em>$port</em> argument is omitted, the <code>z3950</code> service is used; if this is
+not defined, port 210 is used.</p>
+<p>The manager argument may be omitted, in which
+case, the connection is created under the control of a
+``default manager'', a reference to which may be subsequently
+retrieved with the <code>manager()</code> method. Multiple connections made
+with no explicitly-specified manager in this way will all share the
+same implicit manager. The default manager is initially in
+synchronous mode. If you don't understand what this paragraph is on
+about, you should feel free to ignore it.</p>
+<p>Unix-domain socket connections can be made by specifying <code>unix</code> as
+the hostname and the path to the socket file as the port.</p>
+<p>If the connection is created in synchronous mode, (or, if the
+constructor call doesn't specify a mode, if the manager controlling
+the new connection is synchronous), then the constructor does not
+return until either the connection is forged or an error occurs in
+trying to do so. (In the latter case, error information is stored in
+the manager structure.) If the connection is asynchronous, then the
+new object is created and returned before the connection is forged;
+this will happen in parallel with subsequent actions.</p>
+<p><em>This is a lie: connecting is always done synchronously.</em></p>
+<p>If a connection cannot be forged, then <code>$!</code> contains an error code
+indicating what went wrong: this may be one of the usual system error
+codes such as ECONNREFUSED (if there is no server running at the
+specified address); alternatively, it may be set to the distinguished
+value -1 if the TCP/IP connection was correctly forged, but the Z39.50
+<code>Init</code> failed.</p>
+<p>Any of the standard options (including asynchronous
+mode) may be specified as additional arguments. Specifically:</p>
+<pre>
+ $conn = new Net::Z3950::Connection($mgr, $host, $port, async => 1);</pre>
+<p>Works as expected.</p>
+<p>
+</p>
+<h2><a name="option__"><code>option()</code></a></h2>
+<pre>
+ $value = $conn->option($type);
+ $value = $conn->option($type, $newval);</pre>
+<p>Returns <em>$conn</em>'s value of the standard option <em>$type</em>, as
+registered in <em>$conn</em> itself, in the manager which controls it, or in
+the global defaults.</p>
+<p>If <em>$newval</em> is specified, then it is set as the new value of that
+option in <em>$conn</em>, and the option's old value is returned.</p>
+<p>
+</p>
+<h2><a name="manager__"><code>manager()</code></a></h2>
+<pre>
+ $mgr = $conn->manager();</pre>
+<p>Returns a reference to the manager controlling <em>$conn</em>. If <em>$conn</em>
+was created with an explicit manager, then this method will always
+return that function; otherwise, it returns a reference to the single
+global ``default manager'' shared by all other connections.</p>
+<p>
+</p>
+<h2><a name="startsearch__"><code>startSearch()</code></a></h2>
+<pre>
+ $conn->startSearch($srch);
+ $conn->startSearch(-ccl => 'au=kernighan and su=unix');
+ $conn->startSearch(-prefix => '@and @attr 1=1 kernighan @attr 1=21 unix');
+ $conn->startSearch('@and @attr 1=1 kernighan @attr 1=21 unix');</pre>
+<p>Inititiates a new search against the Z39.50 server to which <em>$conn</em>
+is connected. Since this can never fail (:-), it <code>die()s</code> if
+anything goes wrong. But that will never happen. (``Surely the odds
+of that happening are million to one, doctor?'')</p>
+<p>The query itself can be specified in a variety of ways:</p>
+<ul>
+<li></li>
+A <code>Net::Z3950::Query</code> object may be passed in.
+<p></p>
+<li></li>
+A query-type option may be passed in, together with the query string
+itself as its argument. Currently recognised query types are <code>-ccl</code>
+(using the standard CCL query syntax, interpreted by the server),
+<code>-ccl2rpn</code> (CCL query compiled by the client into a type-1 query),
+<code>-prefix</code> (using Index Data's prefix query notation, described at
+<a href="http://indexdata.dk/yaz/doc/tools.php#PQF">http://indexdata.dk/yaz/doc/tools.php#PQF</a> )
+and <code>-cql</code> (passing a CQL query straight through to the server).
+<p></p>
+<li></li>
+A query string alone may be passed in. In this case, it is
+interpreted according to the query type previously established as a
+default for <em>$conn</em> or its manager.
+<p></p></ul>
+<p>The various query types are described in more detail in the
+documentation of the <code>Net::Z3950::Query</code> class.</p>
+<p><em>### The Query class does not yet, and might never, exist.</em></p>
+<p>Some broken Z39.50 server will fault a search but not provide any
+diagnostic records. The correct fix for this problem is of course to
+poke the providers of those servers in the back of the knee with a
+teaspoon until they fix their products. But since this is not always
+practical, <code>Net::Z3950</code> provides a dummy diagnostic record in this
+case, with error-code 3 (``unsupported search'') and additional
+information set to ``no diagnostic records supplied by server''.</p>
+<p>
+</p>
+<h2><a name="startscan__"><code>startScan()</code></a></h2>
+<pre>
+ $conn->startScan($scan);
+ $conn->startScan(-prefix => '@attr 1=5 programming');
+ $conn->startScan('@attr 1=5 programming');</pre>
+<p>Executes a scan against the Z39.50 server to which <em>$conn</em> is
+connected. The scan parameters are represented by a query which is
+analysed for the term itself and the access-point in which it should
+occur. This query can be specified in the same ways as for
+<code>startSearch()</code>.</p>
+<p>
+</p>
+<h2><a name="search__"><code>search()</code></a></h2>
+<pre>
+ $rs = $conn->search($srch);</pre>
+<p>This method performs a blocking search, returning a reference
+to the result set generated by the server. It takes the same
+arguments as <code>startSearch()</code></p>
+<p>
+</p>
+<h2><a name="scan__"><code>scan()</code></a></h2>
+<pre>
+ $sr = $conn->scan($scan);</pre>
+<p>This method performs a blocking scan, returning a reference
+to the scan result generated by the server. It takes the same
+arguments as <code>startScan()</code></p>
+<p>The returned structure is a <code>Net::Z3950::APDU::ScanResponse</code> which
+can be pulled apart by inspection. That may not be the nicest
+possible interface.</p>
+<p>
+</p>
+<h2><a name="op__"><code>op()</code></a></h2>
+<pre>
+ op = $conn->op();
+ if (op == Net::Z3950::Op::Search) { # ...</pre>
+<p>When a connection has been returned from the <code>Net::Z3950::Manager</code> class's
+<code>wait()</code> method, it's known that <em>something</em> has happened to it.
+This method may then be called to find out what. It returns one of
+the following values:</p>
+<dl>
+<dt><strong><a name="item_net_3a_3az3950_3a_3aop_3a_3aerror"><code>Net::Z3950::Op::Error</code></a></strong><br />
+</dt>
+<dd>
+An error occurred. The details may be obtained via the <code>errcode()</code>,
+<code>addinfo()</code> and <code>errop()</code> methods described below.
+</dd>
+<p></p>
+<dt><strong><a name="item_net_3a_3az3950_3a_3aop_3a_3ainit"><code>Net::Z3950::Op::Init</code></a></strong><br />
+</dt>
+<dd>
+An init response was received. The response object may be obtained
+via the <code>initResponse()</code> method described below.
+</dd>
+<p></p>
+<dt><strong><a name="item_net_3a_3az3950_3a_3aop_3a_3asearch"><code>Net::Z3950::Op::Search</code></a></strong><br />
+</dt>
+<dd>
+A search response was received. The result set may be obtained via
+the <code>resultSet()</code> method described below, or the raw APDU object may
+be obtained via <code>searchResponse()</code>.
+</dd>
+<p></p>
+<dt><strong><a name="item_net_3a_3az3950_3a_3aop_3a_3aget"><code>Net::Z3950::Op::Get</code></a></strong><br />
+</dt>
+<dd>
+One or more result-set records have become available. They may be
+obtained via the <code>record()</code> method of the appropriate result set.
+</dd>
+<p></p>
+<dt><strong><a name="item_net_3a_3az3950_3a_3aop_3a_3ascan"><code>Net::Z3950::Op::Scan</code></a></strong><br />
+</dt>
+<dd>
+A scan response was received. The scan-set may be obtained via the
+<code>scanSet()</code> method described below, or the raw APDU object may be
+obtained via <code>scanResponse()</code>.
+</dd>
+<p></p></dl>
+<p>
+</p>
+<h2><a name="errcode____addinfo____errop____errmsg__">errcode(), addinfo(), errop(), <code>errmsg()</code></a></h2>
+<pre>
+ if ($conn->op() == Net::Z3950::Op::Error) {
+ print "error number: ", $conn->errcode(), "\n";
+ print "error message: ", $conn->errmsg(), "\n";
+ print "additional info: ", $conn->errcode(), "\n";
+ print "in function: ", Net::Z3950::opstr($conn->errop()), "\n";
+ }</pre>
+<p>When an error is known to have occurred on a connection, the error
+code (from the BIB-1 diagnosic set) can be retrieved via the
+<code>errcode()</code> method, any additional information via the <code>addinfo()</code>
+method, and the operation that was being attempted when the error
+occurred via the <code>errop()</code> method. (The error operation returned
+takes one of the values that may be returned from the <code>op()</code> method.)</p>
+<p>The meanings of the BIB-1 diagnostics are described at on the Z39.50
+Maintenance Agency web-site at
+<a href="http://lcweb.loc.gov/z3950/agency/defns/bib1diag.html">http://lcweb.loc.gov/z3950/agency/defns/bib1diag.html</a></p>
+<p>As a convenience, <code>$conn-</code>errmsg()> is equivalent to
+<code>Net::Z3950::errstr($conn-</code>errcode())>.</p>
+<p>
+</p>
+<h2><a name="initresponse__"><code>initResponse()</code></a></h2>
+<pre>
+ if ($op == Net::Z3950::Op::Init) {
+ $rs = $conn->initResponse();</pre>
+<p>When a connection is known to have received an init response, the
+response may be accessed via the connection's <code>initResponse()</code>
+method.</p>
+<p>
+</p>
+<h2><a name="searchresponse____resultset__">searchResponse(), <code>resultSet()</code></a></h2>
+<pre>
+ if ($op == Net::Z3950::Op::Search) {
+ $sr = $conn->searchResponse();
+ $rs = $conn->resultSet();</pre>
+<p>When a connection is known to have received a search response, the
+response may be accessed via the connection's <code>searchResponse()</code>, and
+the search result may be accessed via the connection's <code>resultSet()</code>
+method.</p>
+<p>
+</p>
+<h2><a name="scanresponse____scanset__">scanResponse(), <code>scanSet()</code></a></h2>
+<pre>
+ if ($op == Net::Z3950::Op::Scan) {
+ $sr = $conn->scanResponse();
+ $ss = $conn->scanSet();</pre>
+<p>When a connection is known to have received a scan response, the
+response may be accessed via the connection's <code>scanResponse()</code>, and
+the scan-set may be accessed via the connection's <code>scanSet()</code>
+method.</p>
+<p>
+</p>
+<h2><a name="resultsets__"><code>resultSets()</code></a></h2>
+<pre>
+ @rs = $conn->resultSets();</pre>
+<p>Returns a list of all the result sets that have been created across
+the connection <em>$conn</em> and have not subsequently been deleted.</p>
+<p>
+</p>
+<h2><a name="name__"><code>name()</code></a></h2>
+<pre>
+ print $conn->name();</pre>
+<p>Returns a short string which can be used as the connection's ``name'' in
+text output.</p>
+<p>
+</p>
+<h2><a name="close__"><code>close()</code></a></h2>
+<pre>
+ $conn->close();</pre>
+<p>This lets the <code>Net::Z3950</code> module know that you no longer want to use
+<code>$conn</code> so it can be closed. It would be nice if this could be done
+implicitly when <code>$conn</code> goes out of scope, as in:</p>
+<pre>
+ {
+ $conn = new Net::Z3950::Connection($host, $port);
+ $rs = $conn->search($query);
+ print "found ", $rs->size(), " records\n";
+ }</pre>
+<p>But in general this won't work, because <code>$conn</code> is not the only
+reference to the connection object: when it goes out of scope, the
+connection is not destroyed because its manager still holds a
+reference to it. So use <code>$conn-</code>close()> (just before the close
+brace in the example above) to let the connection know it's done with.</p>
+<p>
+</p>
+<hr />
+<h1><a name="author">AUTHOR</a></h1>
+<p>Mike Taylor <<a href="mailto:mike at indexdata.com">mike at indexdata.com</a>></p>
+<p>First version Tuesday 23rd May 2000.</p>
+<p>
+</p>
+<hr />
+<h1><a name="see_also">SEE ALSO</a></h1>
+<p><code>Net::Z3950::Query</code></p>
+
+</body>
+
+</html>
Added: packages/libnet-z3950-perl/trunk/doc/html/Manager.html
===================================================================
--- packages/libnet-z3950-perl/trunk/doc/html/Manager.html 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/doc/html/Manager.html 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,152 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Net::Z3950::Manager - State manager for multiple Z39.50 connections.</title>
+<link rev="made" href="mailto:root at localhost" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#methods">METHODS</a></li>
+ <ul>
+
+ <li><a href="#new__"><code>new()</code></a></li>
+ <li><a href="#option__"><code>option()</code></a></li>
+ <li><a href="#connect__"><code>connect()</code></a></li>
+ <li><a href="#wait__"><code>wait()</code></a></li>
+ <li><a href="#connections__"><code>connections()</code></a></li>
+ <li><a href="#resultsets__"><code>resultSets()</code></a></li>
+ </ul>
+
+ <li><a href="#author">AUTHOR</a></li>
+ <li><a href="#see_also">SEE ALSO</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Net::Z3950::Manager - State manager for multiple Z39.50 connections.</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ $mgr = new Net::Z3950::Manager(async => 1);
+ $conn = $mgr->connect($hostname, $port);
+ # Set up some more connections, then:
+ while ($conn = $mgr->wait()) {
+ # Handle message on $conn
+ }</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>A manager object encapsulates the Net::Z3950 module's global state -
+preferences for search parsing, preferred record syntaxes, compiled
+configuration files, <em>etc.</em> - as well as a list of references to all
+the open connections. It main role is to handle multiplexing between
+the connections that are opened on it.</p>
+<p>We would normally expect there to be just one manager object in a
+program, but I suppose there's no reason why you shouldn't make more
+if you want.</p>
+<p>Simple programs - those which therefore have no requirement for
+multiplexing, perhaps because they connect only to a single server -
+do not need explicitly to create a manager at all: an anonymous
+manager is implicitly created along with the connection.</p>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<p>
+</p>
+<h2><a name="new__"><code>new()</code></a></h2>
+<pre>
+ $mgr = new Net::Z3950::Manager();</pre>
+<p>Creates and returns a new manager. Any of the standard options may be
+specified as arguments; in addition, the following manager-specific
+options are recognised:</p>
+<dl>
+<dt><strong><a name="item_async">async</a></strong><br />
+</dt>
+<dd>
+This is 0 (false) by default, and may be set to 1 (true). The mode
+affects various details of subsequent behaviour - for example, see the
+description of the <code>Net::Z3950::Connection</code> class's <code>new()</code> method.
+</dd>
+<p></p></dl>
+<p>
+</p>
+<h2><a name="option__"><code>option()</code></a></h2>
+<pre>
+ $value = $mgr->option($type);
+ $value = $mgr->option($type, $newval);</pre>
+<p>Returns <em>$mgr</em>'s value of the standard option <em>$type</em>, as registered
+in <em>$mgr</em> or in the global defaults.</p>
+<p>If <em>$newval</em> is specified, then it is set as the new value of that
+option in <em>$mgr</em>, and the option's old value is returned.</p>
+<p>
+</p>
+<h2><a name="connect__"><code>connect()</code></a></h2>
+<pre>
+ $conn = $mgr->connect($hostname, $port);</pre>
+<p>Creates a new connection under the control of the manager <em>$mgr</em>.
+The connection will be forged to the server on the specified <em>$port</em>
+of <$hostname>.</p>
+<p>Additional standard options may be specified after the <em>$port</em>
+argument.</p>
+<p>(This is simply a sugar function to <code>Net::Z3950::Connection-</code>new()>)</p>
+<p>
+</p>
+<h2><a name="wait__"><code>wait()</code></a></h2>
+<pre>
+ $conn = $mgr->wait();</pre>
+<p>Waits for an event to occur on one of the connections under the
+control of <em>$mgr</em>, yielding control to any other event handlers that
+may have been registered with the underlying event loop.</p>
+<p>When a suitable event occurs - typically, a response is received to an
+earlier INIT, SEARCH or PRESENT - the handle of the connection on
+which it occurred is returned: the handle can be further interrogated
+with its <code>op()</code> and related methods.</p>
+<p>If the wait times out (only possible if the manager's <code>timeout</code>
+option has been set), then <code>wait()</code> returns an undefined value.</p>
+<p>
+</p>
+<h2><a name="connections__"><code>connections()</code></a></h2>
+<pre>
+ @conn = $mgr->connections();</pre>
+<p>Returns a list of all the connections that have been opened under the
+control of the manager <em>$mgr</em> and have not subsequently been closed.</p>
+<p>
+</p>
+<h2><a name="resultsets__"><code>resultSets()</code></a></h2>
+<pre>
+ @rs = $mgr->resultSets();</pre>
+<p>Returns a list of all the result sets that have been created across
+the connections associated with the manager <em>$mgr</em> and have not
+subsequently been deleted.</p>
+<p>
+</p>
+<hr />
+<h1><a name="author">AUTHOR</a></h1>
+<p>Mike Taylor <<a href="mailto:mike at indexdata.com">mike at indexdata.com</a>></p>
+<p>First version Tuesday 23rd May 2000.</p>
+<p>
+</p>
+<hr />
+<h1><a name="see_also">SEE ALSO</a></h1>
+<p>List of standard options.</p>
+<p>Discussion of the Net::Z3950 module's use of the Event module.</p>
+
+</body>
+
+</html>
Added: packages/libnet-z3950-perl/trunk/doc/html/Record.html
===================================================================
--- packages/libnet-z3950-perl/trunk/doc/html/Record.html 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/doc/html/Record.html 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,165 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Net::Z3950::Record - base class for records retrieved from a Z39.50 server</title>
+<link rev="made" href="mailto:root at localhost" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#methods">METHODS</a></li>
+ <ul>
+
+ <li><a href="#nfields__"><code>nfields()</code></a></li>
+ <li><a href="#render__"><code>render()</code></a></li>
+ <li><a href="#rawdata__"><code>rawdata()</code></a></li>
+ </ul>
+
+ <li><a href="#subclasses">SUBCLASSES</a></li>
+ <ul>
+
+ <li><a href="#net__z3950__record__sutrs">Net::Z3950::Record::SUTRS</a></li>
+ <li><a href="#net__z3950__record__grs1">Net::Z3950::Record::GRS1</a></li>
+ <li><a href="#net__z3950__record__usmarc__net__z3950__record__ukmarc__net__z3950__record__normarc__net__z3950__record__librismarc__net__z3950__record__danmarc__net__z3950__record__unimarc">Net::Z3950::Record::USMARC, Net::Z3950::Record::UKMARC, Net::Z3950::Record::NORMARC, Net::Z3950::Record::LIBRISMARC, Net::Z3950::Record::DANMARC, Net::Z3950::Record::UNIMARC</a></li>
+ <li><a href="#net__z3950__record__xml">Net::Z3950::Record::XML</a></li>
+ <li><a href="#net__z3950__record__html">Net::Z3950::Record::HTML</a></li>
+ <li><a href="#net__z3950__record__opac">Net::Z3950::Record::OPAC</a></li>
+ <li><a href="#net__z3950__record__mab">Net::Z3950::Record::MAB</a></li>
+ <li><a href="#____others__not_yet_supported">### others, not yet supported</a></li>
+ </ul>
+
+ <li><a href="#author">AUTHOR</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Net::Z3950::Record - base class for records retrieved from a Z39.50 server</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ $rs = $conn->resultSet();
+ $rec = $rs->record($n);
+ print $rec->render();</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>A Record object represents a record retrieved from a Z39.50 server.
+In fact, the <code>Net::Z3950::Record</code> class itself is never instantiated:
+instead, the Net::Z3950 module creates objects of subclasses such as
+<code>Net::Z3950::Record::SUTRS</code>, <code>Net::Z3950::Record::GRS1</code>,
+<code>Net::Z3950::Record::USMARC</code> and <code>Net::Z3950::Record::XML</code>.
+This class defines a common interface which must be supported by all
+such subclasses.</p>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<p>
+</p>
+<h2><a name="nfields__"><code>nfields()</code></a></h2>
+<pre>
+ $count = $rec->nfields();</pre>
+<p>Returns the number of fields in the record <em>$rec</em>.</p>
+<p>
+</p>
+<h2><a name="render__"><code>render()</code></a></h2>
+<pre>
+ print $rec->render();</pre>
+<p>Returns a human-readable string representing the content of the record
+<em>$rec</em> in a form appropriate to its specific type.</p>
+<p>
+</p>
+<h2><a name="rawdata__"><code>rawdata()</code></a></h2>
+<pre>
+ $raw = $rec->rawdata();</pre>
+<p>Returns the raw form of the data in the record, which will in general
+be different in form for different record syntaxes.</p>
+<p>
+</p>
+<hr />
+<h1><a name="subclasses">SUBCLASSES</a></h1>
+<p>
+</p>
+<h2><a name="net__z3950__record__sutrs">Net::Z3950::Record::SUTRS</a></h2>
+<p>Represents a a record using the Simple Unstructured Text Record
+Syntax (SUTRS) - a simple flat string containing the record's data in
+a form suitable for presentation to humans (so that the <code>render()</code>
+and <code>rawdata()</code> methods return the same thing.)</p>
+<p>See Appendix REC.2 (Simple Unstructured Text Record Syntax) of the
+Z39.50 Standard for more information.</p>
+<p>
+</p>
+<h2><a name="net__z3950__record__grs1">Net::Z3950::Record::GRS1</a></h2>
+<p>Represents a record using Generic Record Syntax 1 (GRS1) - a list of
+tagged fields where each tag is made up of a tag type and tag value,
+and each field may be of any type, including numeric, string, and
+recursively contained sub-record. Fields may also be annotated with
+metadata, variant information <em>etc.</em></p>
+<p>See Appendix REC.5 (Generic Record Syntax 1) of the Z39.50 Standard
+for more information.</p>
+<p>
+</p>
+<h2><a name="net__z3950__record__usmarc__net__z3950__record__ukmarc__net__z3950__record__normarc__net__z3950__record__librismarc__net__z3950__record__danmarc__net__z3950__record__unimarc">Net::Z3950::Record::USMARC, Net::Z3950::Record::UKMARC, Net::Z3950::Record::NORMARC, Net::Z3950::Record::LIBRISMARC, Net::Z3950::Record::DANMARC, Net::Z3950::Record::UNIMARC</a></h2>
+<p>Represents a record using the appropriate MARC (MAchine Readable
+Catalogue) format - binary formats used extensively in libraries.</p>
+<p>For further information on the MARC formats, see the Library of
+Congress Network Development and MARC Standards Office web page at
+<a href="http://lcweb.loc.gov/marc/">http://lcweb.loc.gov/marc/</a> and the MARC module in Ed Summers's
+directory at CPAN,
+<a href="http://cpan.valueclick.com/authors/id/E/ES/ESUMMERS/">http://cpan.valueclick.com/authors/id/E/ES/ESUMMERS/</a></p>
+<p>
+</p>
+<h2><a name="net__z3950__record__xml">Net::Z3950::Record::XML</a></h2>
+<p>Represents a a record using XML (Extended Markup Language), as defined
+by the W3C. Rendering is not currently defined: this module treats
+the record as a single opaque lump of data, to be parsed by other
+software.</p>
+<p>For more information about XML, see <a href="http://www.w3.org/XML/">http://www.w3.org/XML/</a></p>
+<p>
+</p>
+<h2><a name="net__z3950__record__html">Net::Z3950::Record::HTML</a></h2>
+<p>Represents a a record using HTML (HyperText Markup Language), as
+defined by the W3C. Rendering is not currently defined: this module
+treats the record as a single opaque lump of data, to be handled by
+other software.</p>
+<p>For more information about HTML, see <a href="http://www.w3.org/MarkUp/">http://www.w3.org/MarkUp/</a></p>
+<p>
+</p>
+<h2><a name="net__z3950__record__opac">Net::Z3950::Record::OPAC</a></h2>
+<p>Represents a a record using the OPAC (Online Public Access Catalogue)
+record syntax, as defined in Appendix 5 (REC) of the Z39.50 standard
+at <a href="http://lcweb.loc.gov/z3950/agency/asn1.html#RecordSyntax-opac">http://lcweb.loc.gov/z3950/agency/asn1.html#RecordSyntax-opac</a></p>
+<p>
+</p>
+<h2><a name="net__z3950__record__mab">Net::Z3950::Record::MAB</a></h2>
+<p>Represents a record using the MAB record syntax (Maschinelles
+Austauschformat fuer Bibliotheken, <a href="ftp://ftp.ddb.de/pub/mab/);">ftp://ftp.ddb.de/pub/mab/);</a> an
+interchange format defined by Die Deutsche Bibliothek (German National
+Library).</p>
+<p>
+</p>
+<h2><a name="____others__not_yet_supported">### others, not yet supported</a></h2>
+<p>
+</p>
+<hr />
+<h1><a name="author">AUTHOR</a></h1>
+<p>Mike Taylor <<a href="mailto:mike at indexdata.com">mike at indexdata.com</a>></p>
+<p>First version Sunday 4th May 2000.</p>
+
+</body>
+
+</html>
Added: packages/libnet-z3950-perl/trunk/doc/html/ResultSet.html
===================================================================
--- packages/libnet-z3950-perl/trunk/doc/html/ResultSet.html 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/doc/html/ResultSet.html 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,191 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Net::Z3950::ResultSet - result set received in response to a Z39.50 search</title>
+<link rev="made" href="mailto:root at localhost" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#methods">METHODS</a></li>
+ <ul>
+
+ <li><a href="#size__"><code>size()</code></a></li>
+ <li><a href="#subquerycount__"><code>subqueryCount()</code></a></li>
+ <li><a href="#present__"><code>present()</code></a></li>
+ <li><a href="#record__"><code>record()</code></a></li>
+ <li><a href="#records__"><code>records()</code></a></li>
+ <li><a href="#delete__"><code>delete()</code></a></li>
+ <li><a href="#errcode____addinfo____errmsg__">errcode(), addinfo(), <code>errmsg()</code></a></li>
+ <li><a href="#option__"><code>option()</code></a></li>
+ </ul>
+
+ <li><a href="#author">AUTHOR</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Net::Z3950::ResultSet - result set received in response to a Z39.50 search</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ if ($conn->op() == Net::Z3950::Op::Search) {
+ $rs = $conn->resultSet();
+ $size = $rs->size();</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>A ResultSet object represents the set of records found by a Z39.50
+server in response to a search. At any given time, none, some or all
+of the records may have been physcially transferred to the client; a
+cache is maintained.</p>
+<p>Note that there is no constructor for this class (or at least, none
+that I'm going to tell you about :-) ResultSet objects are always
+created by the Net::Z3950 module itself, and are returned to the caller
+via the <code>Net::Z3950::Connection</code> class's <code>resultSet()</code> method.</p>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<p>
+</p>
+<h2><a name="size__"><code>size()</code></a></h2>
+<pre>
+ $nrecords = $rs->size();</pre>
+<p>Returns the number of records in the result set <em>$rs</em></p>
+<p>
+</p>
+<h2><a name="subquerycount__"><code>subqueryCount()</code></a></h2>
+<pre>
+ $subquery = $rs->subqueryCount();</pre>
+<p>Returns hit count of subquery terms as a hash reference containing
+(term, count) pairs, if the server returned this information. If the
+information is not available, an undefined value is returned.</p>
+<p>
+</p>
+<h2><a name="present__"><code>present()</code></a></h2>
+<pre>
+ $rs->present($start, $count) or die "failed: $rs->{errcode}\n";</pre>
+<p>Causes any records in the specified range that are not yet in the
+cache to be retrieved from the server. By calling this method before
+retrieving individual records with <code>record()</code>, you avoid sending lots
+of small requests for single records across the network. In
+asynchronous mode, <code>present()</code> just schedules the records for
+retrieval.</p>
+<p>Note that <code>$start</code> is indexed from 1.</p>
+<p>In synchronous mode, returns 1 if the records were successfully
+retrieved, 0 if an error occurred. In asynchronous mode, returns 1 if
+new requests were queued, 0 if all of the requested records had
+already been queued.</p>
+<p>
+</p>
+<h2><a name="record__"><code>record()</code></a></h2>
+<pre>
+ $rec = $rs->record($n);</pre>
+<p>Returns a reference to <em>$n</em>th record in the result set <em>$rs</em>, if the
+content of that record is known. Valid values of <em>$n</em> range from 1
+to the return value of the <code>size()</code> method.</p>
+<p>If the record is not available, an undefined value is returned, and
+diagnostic information made available via <em>$rs</em>'s <code>errcode()</code> and
+<code>addinfo()</code> methods.</p>
+<p>As a special case, when the connection is anychronous, the
+<code>errcode()</code> may be zero, indicating simply that the record has not
+yet been fetched from the server. In this case, the calling code
+should try again later. (How much later? As a rule of thumb, after
+it's done ``something else'', such as request another record or issue
+another search.) This can never happen in synchronous mode.</p>
+<p>
+</p>
+<h2><a name="records__"><code>records()</code></a></h2>
+<pre>
+ @records = $rs->records();
+ foreach $rec (@records) {
+ print $rec->render();
+ }</pre>
+<p>This utility method returns a list of all the records in the result
+set I$<rs>. Because Perl arrays are indexed from zero, the first
+record is <code>$records[0]</code>, the second is <code>$records[1]</code>, <em>etc.</em></p>
+<p>If not all the records associated with <em>$rs</em> have yet been
+transferred from the server, then they need to be transferred at this
+point. This means that the <code>records()</code> method may block, and so is
+not recommended for use in applications that interact with multiple
+servers simultaneously. It does also have the side-effect that
+subsequent invocations of the <code>record()</code> method will always
+immediately return either a legitimate record or a ``real error''
+rather than a ``not yet'' indicator.</p>
+<p>If an error occurs, an empty list is returned. Since this is also
+what's returned when the search had zero hits, well-behaved
+applications will consult <code>$rs-</code>size()> in these circumstances to
+determine which of these two conditions pertains. After an error has
+occurred, details may be obtained via the result set's <code>errcode()</code>
+and <code>addinfo()</code> methods.</p>
+<p>If a non-empty list is returned, then individual elements of that list
+may still be undefined, indicating that corresponding record could not
+be fetched. In order to get more information, it's necessary to
+attempt to fetch the record using the <code>record()</code> method, then consult
+the <code>errcode()</code> and <code>addinfo()</code> methods.</p>
+<p><strong>Unwarranted personal opinion</strong>: all in all, this method is a pleasant
+short-cut for trivial programs to use, but probably carries too many
+caveats to be used extensively in serious applications. You may want to
+take a look at <code>present()</code> and the <code>prefetch</code> option instead.</p>
+<p><strong>AS OF RELEASE 0.31, THIS METHOD IS NOW DEPRECATED.
+PLEASE USE record() INSTEAD.</strong></p>
+<p>
+</p>
+<h2><a name="delete__"><code>delete()</code></a></h2>
+<pre>
+ $ok = $rs->delete();
+ if (!$ok) {
+ print "can't delete: ", $rs->errmsg(), "\n";
+ }</pre>
+<p>Requests the server to delete the result set corresponding to <code>$rs</code>.
+Return non-zero on success, zero on failure.</p>
+<p>
+</p>
+<h2><a name="errcode____addinfo____errmsg__">errcode(), addinfo(), <code>errmsg()</code></a></h2>
+<pre>
+ if (!defined $rs->record($i)) {
+ print "error ", $rs->errcode(), " (", $rs->errmsg(), ")\n";
+ print "additional info: ", $rs->addinfo(), "\n";
+ }</pre>
+<p>When a result set's <code>record()</code> method returns an undefined value,
+indicating an error, it also sets into the result set the BIB-1 error
+code and additional information returned by the server. They can be
+retrieved via the <code>errcode()</code> and <code>addinfo()</code> methods.</p>
+<p>As a convenience, <code>$rs-</code>errmsg()> is equivalent to
+<code>Net::Z3950::errstr($rs-</code>errcode())>.</p>
+<p>
+</p>
+<h2><a name="option__"><code>option()</code></a></h2>
+<pre>
+ $value = $rs->option($type);
+ $value = $rs->option($type, $newval);</pre>
+<p>Returns <em>$rs</em>'s value of the standard option <em>$type</em>, as registered
+in <em>$rs</em> itself, in the connection across which it was created, in
+the manager which controls that connection, or in the global defaults.</p>
+<p>If <em>$newval</em> is specified, then it is set as the new value of that
+option in <em>$rs</em>, and the option's old value is returned.</p>
+<p>
+</p>
+<hr />
+<h1><a name="author">AUTHOR</a></h1>
+<p>Mike Taylor <<a href="mailto:mike at indexdata.com">mike at indexdata.com</a>></p>
+<p>First version Sunday 28th May 2000.</p>
+
+</body>
+
+</html>
Added: packages/libnet-z3950-perl/trunk/doc/html/Tutorial.html
===================================================================
--- packages/libnet-z3950-perl/trunk/doc/html/Tutorial.html 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/doc/html/Tutorial.html 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,757 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Net::Z3950::Tutorial - tutorial for the Net::Z3950 module</title>
+<link rev="made" href="mailto:root at localhost" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#a_very_simple_client">A VERY SIMPLE CLIENT</a></li>
+ <li><a href="#how_it_works">HOW IT WORKS</a></li>
+ <li><a href="#more_complex_behaviour">MORE COMPLEX BEHAVIOUR</a></li>
+ <ul>
+
+ <li><a href="#searching">Searching</a></li>
+ <li><a href="#retrieval">Retrieval</a></li>
+ <li><a href="#scanning">Scanning</a></li>
+ </ul>
+
+ <li><a href="#what_to_do_with_your_records">WHAT TO DO WITH YOUR RECORDS</a></li>
+ <ul>
+
+ <li><a href="#marc_records">MARC RECORDS</a></li>
+ <li><a href="#grs1_records">GRS-1 RECORDS</a></li>
+ </ul>
+
+ <li><a href="#changing_session_parameters">CHANGING SESSION PARAMETERS</a></li>
+ <ul>
+
+ <li><a href="#make_or_find_a_manager">Make or Find a Manager</a></li>
+ <li><a href="#set_the_parameters">Set the Parameters</a></li>
+ </ul>
+
+ <li><a href="#option_inheritance">OPTION INHERITANCE</a></li>
+ <li><a href="#asynchronous_mode">ASYNCHRONOUS MODE</a></li>
+ <li><a href="#now_what">NOW WHAT?</a></li>
+ <li><a href="#author">AUTHOR</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Net::Z3950::Tutorial - tutorial for the Net::Z3950 module</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<p>Apparently, every POD document has to have a SYNOPSIS. So here's one.</p>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p><code>Net::Z3950</code> is a Perl module for writing Z39.50 clients. (If you
+want to write a Z39.50 server, you want the
+<code>Net::Z3950::SimpleServer</code> module.)</p>
+<p>Its goal is to hide all the messy details of the Z39.50 protocol - at
+least by default - while providing access to all of its glorious
+power. Sometimes, this involves revealing the messy details after
+all, but at least this is the programmer's choice. The result is that
+writing Z39.50 clients works the way it should according my favourite
+of the various Perl mottos: ``Simple things should be simple, and
+difficult things should be possible.''</p>
+<p>If you don't know what Z39.50 is, then the best place to find out is
+at
+<a href="http://lcweb.loc.gov/z3950/agency/">http://lcweb.loc.gov/z3950/agency/</a>
+the web site of the Z39.50 Maintenance Agency. Among its many other
+delights, this site contains a complete downloadable soft-copy of the
+standard itself. In briefest summary, Z39.50 is the international
+standard for distributed searching and retrieval.</p>
+<p>
+</p>
+<hr />
+<h1><a name="a_very_simple_client">A VERY SIMPLE CLIENT</a></h1>
+<p>The <code>Net::Z3950</code> distribution includes a couple of sample clients in
+the <code>samples</code> directory. The simplest of them, <code>trivial.pl</code> reads
+as follows:</p>
+<pre>
+ use Net::Z3950;
+ $conn = new Net::Z3950::Connection('indexdata.dk', 210,
+ databaseName => 'gils');
+ $rs = $conn->search('mineral');
+ print "found ", $rs->size(), " records:\n";
+ my $rec = $rs->record(1);
+ print $rec->render();</pre>
+<p>This complete program retrieves from the database called ``gils'' on
+the Z39.50 server on port 210 of <code>indexdata.dk</code> the first record
+matching the search ``mineral'', and renders it in human-readable
+form. Typical output would look like this:</p>
+<pre>
+ 6 fields:
+ (1,1) 1.2.840.10003.13.2
+ (1,14) "2"
+ (2,1) {
+ (1,19) "UTAH EARTHQUAKE EPICENTERS"
+ (3,Acronym) "UUCCSEIS"
+ }
+ (4,52) "UTAH GEOLOGICAL AND MINERAL SURVEY"
+ (4,1) "ESDD0006"
+ (1,16) "198903"</pre>
+<p>
+</p>
+<hr />
+<h1><a name="how_it_works">HOW IT WORKS</a></h1>
+<p>Let's pick the trivial client apart line by line (it won't take long!)</p>
+<pre>
+ use Net::Z3950;</pre>
+<p>This line simply tells Perl to pull in the <code>Net::Z3950</code> module - a
+prerequisite for using types like <code>Net::Z3950::Connection</code>.</p>
+<pre>
+ $conn = new Net::Z3950::Connection('indexdata.dk', 210,
+ databaseName => 'gils');</pre>
+<p>Creates a new connection to the Z39.50 server on port 210 of the host
+<code>indexdata.dk</code>, noting that searches on this connection will default
+to the database called ``gils''. A reference to the new connection is
+stored in <code>$conn</code>.</p>
+<pre>
+ $rs = $conn->search('mineral');</pre>
+<p>Performs a single-word search on the connection referenced by <code>$conn</code>
+(in the previously established default database, ``gils''.) In
+response, the server generates an <em>result set</em>, notionally containing
+all the matching records; a reference to the new connection is stored
+in <code>$rs</code>.</p>
+<pre>
+ print "found ", $rs->size(), " records:\n";</pre>
+<p>Prints the number of records in the new result set <code>$rs</code>.</p>
+<pre>
+ my $rec = $rs->record(1);</pre>
+<p>Fetches from the server the first record in the result set <code>$rs</code>,
+requesting the default record syntax (GRS-1) and the default element
+set (brief, ``b''); a reference to the newly retrieved record is
+stored in <code>$rec</code>.</p>
+<pre>
+ print $rec->render();</pre>
+<p>Prints a human-readable rendition of the record <code>$rec</code>. The exact
+format of the rendition is dependent on issues like the record syntax
+of the record that the server sent.</p>
+<p>
+</p>
+<hr />
+<h1><a name="more_complex_behaviour">MORE COMPLEX BEHAVIOUR</a></h1>
+<p>
+</p>
+<h2><a name="searching">Searching</a></h2>
+<p>Searches may be specified in one of several different syntaxes.
+The default
+syntax is so-called Prefix Query Notation, or PQN, a bespoke format
+invented by Index Data to map simply to the Z39.50 type-1 query
+structure. A second is the Common Command Language (CCL) an
+international standard query language often used in libraries.
+The third is the Common Query Language (CQL) the query language
+used by SRW and SRU.</p>
+<p>CCL queries may be interpreted on the client side and translated into
+a type-1 query which is forwarded to the server; or it may be sent
+``as is'' for the server to interpret as it may. CQL queries may only
+be passed ``as is''.</p>
+<p>The interpretation of the search string may be specified by passing an
+argument of <code>-prefix</code>, <code>-ccl</code>, <code>-ccl2rpn</code> or <code>-cql</code> to the <code>search()</code>
+method before the search string itself, as follows:</p>
+<p><strong>Prefix Queries</strong></p>
+<pre>
+ $rs = $conn->search(-prefix => '@or rock @attr 1=21 mineral');</pre>
+<p>Prefix Query Notation is fully described in section 8.1 (<strong>Query
+Syntax Parsers</strong>) of the Yaz toolkit documentation, <strong>YAZ User's Guide
+and Reference</strong>.</p>
+<p>Briefly, however, keywords begin with an <code>@</code>-sign, and all other
+words are interpreted as search terms. Keywords include the binary
+operators <code>@and</code> and <code>@or</code>, which join together the two operands
+that follow them, and <code>@attr</code>, which introduces a <em>type</em>=<em>value</em>
+expression specifying an attribute to be applied to the following
+term.</p>
+<p>So:</p>
+<ul>
+<li></li>
+<code>fruit</code> searches for the term ``fruit'',
+<p></p>
+<li></li>
+<code>@and fruit fish</code> searches for records containing both ``fruit'' and
+``fish'',
+<p></p>
+<li></li>
+<code>@or fish chicken</code> searches for records containing either ``fish'' or
+``chicken'' (or both),
+<p></p>
+<li></li>
+<code>@and fruit @or fish chicken</code> searches for records containing both
+``fruit'' and at least one of ``fish'' or ``chicken''.
+<p></p>
+<li></li>
+<code>@or rock @attr 1=21 mineral</code> searches for records either containing
+``rock'' or ``mineral'', but with the ``mineral'' search term carrying
+an attribute of type 1, with value 21 (typically interpreted to mean
+that the search term must occur in the ``subject'' field of the
+record.)
+<p></p></ul>
+<p><strong>CCL Queries</strong></p>
+<pre>
+ $rs = $conn->search(-ccl2rpn => 'rock or su=mineral');
+ $rs = $conn->search(-ccl => 'rock or su=mineral');</pre>
+<p>CCL is formally specified in the international standard ISO 8777
+(<strong>Commands for interactive text searching</strong>) and also described in
+section 8.1 (<strong>Query Syntax Parsers</strong>) of the Yaz toolkit
+documentation, <strong>YAZ User's Guide and Reference</strong>.</p>
+<p>Briefly, however, there is a set of well-known keywords including
+<code>and</code>, <code>or</code> and <code>not</code>. Words other than these are interpreted as
+search terms. Operating grouping (precedence) is specified by
+parentheses, and the semantics of a search term may be modified by
+prepending one or more comma-separated qualifiers qualifiers and an
+equals sign.</p>
+<p>So:</p>
+<ul>
+<li></li>
+<code>fruit</code> searches for the term ``fruit'',
+<p></p>
+<li></li>
+<code>fruit and fish</code> searches for records containing both ``fruit'' and
+``fish'',
+<p></p>
+<li></li>
+<code>fish or chicken</code> searches for records containing either ``fish'' or
+``chicken'' (or both),
+<p></p>
+<li></li>
+<code>fruit and (fish or chicken)</code> searches for records containing both
+``fruit'' and at least one of ``fish'' or ``chicken''.
+<p></p>
+<li></li>
+<code>rock or su=mineral</code> searches for records either containing
+``rock'' or ``mineral'', but with the ``mineral'' search term modified
+by the qualifier ``su'' (typically interpreted to mean that the search
+term must occur in the ``subject'' field of the record.)
+<p></p></ul>
+<p>For CCL searches sent directly to the server (query type <code>ccl</code>), the
+exact interpretation of the qualifiers is the server's
+responsibility. For searches compiled on the client side (query side
+<code>ccl2rpn</code>) the interpretation of the qualifiers in terms of type-1
+attributes is determined by the contents of a file called
+<em>### not yet implemented</em>.
+The format of this file is described in the Yaz documentation.</p>
+<p><strong>CQL Queries</strong></p>
+<pre>
+ $rs = $conn->search(-cql => 'au-(kernighan and ritchie)');</pre>
+<p>CQL syntax is very similar to that of CCL.</p>
+<p><strong>Setting Search Defaults</strong></p>
+<p>As an alternative to explicitly specifying the query type when
+invoking the <code>search()</code> method, you can change the connection's
+default query type using its <code>option()</code> method:</p>
+<pre>
+ $conn->option(querytype => 'prefix');
+ $conn->option(querytype => 'ccl');
+ $conn->option(querytype => 'ccl2rpn');</pre>
+<p>The connection's current default query type can be retrieved using
+<code>option()</code> with no ``value'' argument:</p>
+<pre>
+ $qt = $conn->option('querytype');</pre>
+<p>The <code>option()</code> method can be used to set and get numerous other
+defaults described in this document and elsewhere; this method exists
+not only on connections but also on managers (q.v.) and result sets.</p>
+<p>Another important option is <a href="#item_databasename"><code>databaseName</code></a>, whose value specifies
+which database is to be searched.</p>
+<p>
+</p>
+<h2><a name="retrieval">Retrieval</a></h2>
+<p>By default, records are requested from the server one at a time;
+this can be quite slow when retrieving several records. There are two
+ways of improving this. First, the <code>present()</code> method can be used to
+explicitly precharge the cache. Its parameters are a start record and
+record count. In the following example, the <code>present()</code> is optional and
+merely makes the code run faster:</p>
+<pre>
+ $rs->present(11, 5) or die ".....";
+ foreach my $i (11..15) {
+ my $rec = $rs->record($i);
+ ...
+ }</pre>
+<p>The second way is with the <code>prefetch</code> option. Setting this to a
+positive integer makes the <code>record()</code> method fetch the next N
+records and place them in the cache if the the current record
+isn't already there. So the following code would cause two bouts of
+network activity, each retrieving 10 records.</p>
+<pre>
+ $rs->option(prefetch => 10);
+ foreach my $i (1..20) {
+ my $rec = $rs->record($i);
+ ...
+ }</pre>
+<p>In asynchronous mode, <code>present()</code> and <code>prefetch</code> merely cause the
+records to be scheduled for retrieval.</p>
+<p><strong>Element Set</strong></p>
+<p>The default element set is ``b'' (brief). To change this, set the
+result set's <a href="#item_elementsetname"><code>elementSetName</code></a> option:</p>
+<pre>
+ $rs->option(elementSetName => "f");</pre>
+<p><strong>Record Syntax</strong></p>
+<p>The default record syntax preferred by the <code>Net::Z3950</code> module is
+GRS-1 (the One True Record syntax). If, however, you need to ask the
+server for a record using a different record syntax, then the way to
+do this is to set the <a href="#item_preferredrecordsyntax"><code>preferredRecordSyntax</code></a> option of the result
+set from which the record is to be fetched:</p>
+<pre>
+ $rs->option(preferredRecordSyntax => "SUTRS");</pre>
+<p>The record syntaxes which may be requested are listed in the
+<code>Net::Z3950::RecordSyntax</code> enumeration in the file <code>Net/Z3950.pm</code>;
+they include
+<code>Net::Z3950::RecordSyntax::GRS1</code>,
+<code>Net::Z3950::RecordSyntax::SUTRS</code>,
+<code>Net::Z3950::RecordSyntax::USMARC</code>,
+<code>Net::Z3950::RecordSyntax::TEXT_XML</code>,
+<code>Net::Z3950::RecordSyntax::APPLICATION_XML</code>
+and
+<code>Net::Z3950::RecordSyntax::TEXT_HTML</code></p>
+<p>(As always, <code>option()</code> may also be invoked with no ``value''
+parameter to return the current value of the option.)</p>
+<p>
+</p>
+<h2><a name="scanning">Scanning</a></h2>
+<p><strong>### Note to self - write this section!</strong></p>
+<p>
+</p>
+<hr />
+<h1><a name="what_to_do_with_your_records">WHAT TO DO WITH YOUR RECORDS</a></h1>
+<p>Once you've retrieved a record, what can you do with it?</p>
+<p>There are two broad approaches. One is just to display it to the
+user: this can always be done with the <code>render()</code> method, as used in
+the sample code above, whatever the record syntax of the record.</p>
+<p>The more sophisticated approach is to perform appropriate analysis and
+manipulation of the raw record according to the record syntax. The
+raw data is retrieved using the <code>rawdata()</code> method, and the record
+syntax can be determined using the universal <code>isa()</code> method:</p>
+<pre>
+ $raw = $rec->rawdata();
+ if ($rec->isa('Net::Z3950::Record::GRS1')) {
+ process_grs1_record($raw);
+ elsif ($rec->isa('Net::Z3950::Record::USMARC')) {
+ process_marc_record($raw);
+ } # etc.</pre>
+<p>
+</p>
+<h2><a name="marc_records">MARC RECORDS</a></h2>
+<p>For further manipulation of MARC records, we recommend the existing
+MARC module in Ed Summers's directory at CPAN,
+<a href="http://cpan.valueclick.com/authors/id/E/ES/ESUMMERS/">http://cpan.valueclick.com/authors/id/E/ES/ESUMMERS/</a></p>
+<p>
+</p>
+<h2><a name="grs1_records">GRS-1 RECORDS</a></h2>
+<p>The raw data of GRS-1 records in the <code>Net::Z3950</code> module closely
+follows the structure of physcial GRS-1 records - see Appendices REC.5
+(<strong>Generic Record Syntax 1</strong>), TAG (<strong>TagSet Definitions and Schemas</strong>)
+and RET (<strong>Z39.50 Retrieval</strong>) of the standard more details.</p>
+<p>The raw GRS-1 data is intended to be more or less self-describing, but
+here is a summary.</p>
+<ul>
+<li></li>
+The raw data is a reference to an array of elements, each representing
+one of the fields of the record.
+<p></p>
+<li></li>
+Each element is a <code>Net::Z3950::APDU::TaggedElement</code> object. These
+objects support the accessor methods <code>tagType()</code>, <code>tagValue()</code>,
+<code>tagOccurrence()</code> and <code>content()</code>; the first three of these return
+numeric values, or strings in the less common case of string
+tag-values.
+<p></p>
+<li></li>
+The <code>content()</code> of an element is an object of type
+<code>Net::Z3950::ElementData</code>. Its <code>which()</code> method returns a constant
+indicating the type of the content, which may be any of the following:
+<ul>
+<li></li>
+<code>Net::Z3950::ElementData::Numeric</code>
+indicates that the content is a number;
+access it via the
+<code>numeric()</code>
+method.
+<p></p>
+<li></li>
+<code>Net::Z3950::ElementData::String</code>
+indicates that the content is a string of characters;
+access it via the
+<code>string()</code>
+method.
+<p></p>
+<li></li>
+<code>Net::Z3950::ElementData::OID</code>
+indicates that the content is an OID, represented as a string with the
+components separated by periods (``<code>.</code>'');
+access it via the
+<code>oid()</code>
+method.
+<p></p>
+<li></li>
+<code>Net::Z3950::ElementData::Subtree</code>
+is
+a reference to another <code>Net::Z3950::Record::GRS1</code> object, enabling
+arbitrary recursive nesting;
+access it via the
+<code>subtree()</code>
+method.
+<p></p></ul>
+</ul>
+<p>In the future, we plan to take you away from all this by introducing a
+<code>Net::Z3950::Data</code> module which provides a DOM-like interface for
+walking hierarchically structured records independently of their
+record syntax. Keep watchin', kids!</p>
+<p>
+</p>
+<hr />
+<h1><a name="changing_session_parameters">CHANGING SESSION PARAMETERS</a></h1>
+<p>As with customising searching or retrieval behaviour, whole-session
+behaviour is customised by setting options. However, this needs to be
+done before the session is created, because the Z39.50 protocol
+doesn't provide a method for changing (for example) the preferred
+message size of an existing connection.</p>
+<p>In the <code>Net::Z3950</code> module, this is done by creating a <em>manager</em> - a
+controller for one or more connections. Then the manager's options
+can be set; then connections which are opened through the manager use
+the specified values for those options.</p>
+<p>As a matter of fact, <em>every</em> connection is made through a manager.
+If one is not specified in the connection constructor, then the
+``default manager'' is used; it's automatically created the first time
+it's needed, then re-used for any other connections that need it.</p>
+<p>
+</p>
+<h2><a name="make_or_find_a_manager">Make or Find a Manager</a></h2>
+<p>A new manager is created as follows:</p>
+<pre>
+ $mgr = new Net::Z3950::Manager();</pre>
+<p>Once the manager exists, a new connection can be made through it by
+specifying the manager reference as the first argument to the connection
+constructor:</p>
+<pre>
+ $conn = new Net::Z3950::Connection($mgr, 'indexdata.dk', 210);</pre>
+<p>Or equivalently,</p>
+<pre>
+ $conn = $mgr->connect('indexdata.dk', 210);</pre>
+<p>In order to retrieve the manager through which a connection was made,
+whether it was the implicit default manager or not, use the
+<code>manager()</code> method:</p>
+<pre>
+ $mgr = $conn->manager();</pre>
+<p>
+</p>
+<h2><a name="set_the_parameters">Set the Parameters</a></h2>
+<p>There are two ways to set parameters. One we have already seen: the
+<code>option()</code> method can be used to get and set option values for
+managers just as it can for connections and result sets:</p>
+<pre>
+ $pms = $mgr->option('preferredMessageSize');
+ $mgr->option(preferredMessageSize => $pms*2);</pre>
+<p>Alternatively, options may be passed to the manager constructor when
+the manager is first created:</p>
+<pre>
+ $mgr = new Net::Z3950::Manager(
+ preferredMessageSize => 100*1024,
+ maximumRecordSize => 10*1024*1024,
+ preferredRecordSyntax => "GRS-1");</pre>
+<p>This is <em>exactly</em> equivalent to creating a ``vanilla'' manager with
+<code>new Net::Z3950::Manager()</code>, then setting the three options with the
+<code>option()</code> method.</p>
+<p><strong>Message Size Parameters</strong></p>
+<p>The <a href="#item_preferredmessagesize"><code>preferredMessageSize</code></a> and <a href="#item_maximumrecordsize"><code>maximumRecordSize</code></a> parameters can be
+used to specify values of the corresponding parameters which are
+proposed to the server at initialisation time (although the server is
+not bound to honour them.) See sections 3.2.1.1.4
+(<strong>Preferred-message-size and Exceptional-message-size</strong>) and 3.3
+(<strong>Message/Record Size and Segmentation</strong>) of the Z39.50 standard
+itself for details.</p>
+<p>Both options default to one megabyte.</p>
+<p><strong>Implementation Identification</strong></p>
+<p>The <a href="#item_implementationid"><code>implementationId</code></a>, <a href="#item_implementationname"><code>implementationName</code></a> and
+<a href="#item_implementationversion"><code>implementationVersion</code></a> options can be used to control the
+corresponding parameters in initialisation request sent to the server
+to identify the client. The default values are listed below in the
+section <strong>OPTION INHERITANCE</strong>.</p>
+<p><strong>Authentication</strong></p>
+<p>The <a href="#item_user"><code>user</code></a>, <a href="#item_pass"><code>pass</code></a> and <a href="#item_group"><code>group</code></a> options can be specified for a
+manager so that they are passed as identification tokens at
+initialisation time to any connections opened through that manager.
+The three options are interpreted as follows:</p>
+<ul>
+<li></li>
+If <a href="#item_user"><code>user</code></a> is not specified, then authentication is omitted (which is
+more or less the same as ``anonymous'' authentication).
+<p></p>
+<li></li>
+If <a href="#item_user"><code>user</code></a> is specified but not <a href="#item_pass"><code>pass</code></a>, then the value of the
+<a href="#item_user"><code>user</code></a> option is passed as an ``open'' authentication token.
+<p></p>
+<li></li>
+If both <a href="#item_user"><code>user</code></a> and <a href="#item_pass"><code>pass</code></a> are specified, then their values are
+passed in an ``idPass'' authentication structure, together with the
+value of <a href="#item_group"><code>group</code></a> if is it specified.
+<p></p></ul>
+<p>By default, all three options are undefined, so no authentication is
+used.</p>
+<p><strong>Character set and language negotiation</strong></p>
+<p>The <a href="#item_charset"><code>charset</code></a> and <a href="#item_language"><code>language</code></a> options can be used to negotiate the
+character set and language to be used for connections opened through
+that manager. If these options are set, they are passed to the server
+in a character-negotition otherInfo package attached to the
+initialisation request.</p>
+<p>
+</p>
+<hr />
+<h1><a name="option_inheritance">OPTION INHERITANCE</a></h1>
+<p>The values of options are inherited from managers to connections,
+result sets and finally to records.</p>
+<p>This means that when a record is asked for an option value (whether by
+an application invoking its <code>option()</code> method, or by code inside the
+module that needs to know how to behave), that value is looked for
+first in the record's own table of options; then, if it's not
+specified there, in the options of the result set from which the
+record was retrieved; then if it's not specified there, in those of
+the connection across which the result set was found; and finally, if
+not specified there either, in the options for the manager through
+which the connection was created.</p>
+<p>Similarly, option values requested from a result set are looked up (if
+not specified in the result set itself) in the connection, then the
+manager; and values requested from a connection fall back to its
+manager.</p>
+<p>This is why it made sense in an earlier example (see the section <strong>Set
+the Parameters</strong>) to specify a value for the <a href="#item_preferredrecordsyntax"><code>preferredRecordSyntax</code></a>
+option when creating a manager: the result of this is that, unless
+overridden, it will be the preferred record syntax when any record is
+retrieved from any result set retrieved from any connection created
+through that manager. In effect, it establishes a global default.
+Alternatively, one might specify different defaults on two different
+connections.</p>
+<p>In all cases, if the manager doesn't have a value for the requested
+option, then a hard-wired default is used. The defaults are as
+follows. (Please excuse the execrable formatting - that's what
+<code>pod2html</code> does, and there's no sensible way around it.)</p>
+<dl>
+<dt><strong><a name="item_die_handler"><code>die_handler</code></a></strong><br />
+</dt>
+<dd>
+<code>undef</code>
+A function to invoke if <code>die()</code> is called within the main event loop.
+</dd>
+<p></p>
+<dt><strong><a name="item_timeout"><code>timeout</code></a></strong><br />
+</dt>
+<dd>
+<code>undef</code>
+The maximum number of seconds a manager will wait when its <code>wait()</code>
+method is called. If the timeout elapses, <code>wait()</code> returns an
+undefined value. <strong>Can not be set on a per-connection basis.</strong>
+</dd>
+<p></p>
+<dt><strong><a name="item_async"><code>async</code></a></strong><br />
+</dt>
+<dd>
+<code>0</code>
+(Determines whether a given connection is in asynchronous mode.)
+</dd>
+<p></p>
+<dt><strong><a name="item_preferredmessagesize"><code>preferredMessageSize</code></a></strong><br />
+</dt>
+<dd>
+<code>1024*1024</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_maximumrecordsize"><code>maximumRecordSize</code></a></strong><br />
+</dt>
+<dd>
+<code>1024*1024</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_user"><code>user</code></a></strong><br />
+</dt>
+<dd>
+<code>undef</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_pass"><code>pass</code></a></strong><br />
+</dt>
+<dd>
+<code>undef</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_group"><code>group</code></a></strong><br />
+</dt>
+<dd>
+<code>undef</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_implementationid"><code>implementationId</code></a></strong><br />
+</dt>
+<dd>
+<code>'Mike Taylor (id=169)'</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_implementationname"><code>implementationName</code></a></strong><br />
+</dt>
+<dd>
+<code>'Net::Z3950.pm (Perl)'</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_implementationversion"><code>implementationVersion</code></a></strong><br />
+</dt>
+<dd>
+<code>$Net::Z3950::VERSION</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_charset"><code>charset</code></a></strong><br />
+</dt>
+<dd>
+<code>undef</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_language"><code>language</code></a></strong><br />
+</dt>
+<dd>
+<code>undef</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_querytype"><code>querytype</code></a></strong><br />
+</dt>
+<dd>
+<code>'prefix'</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_databasename"><code>databaseName</code></a></strong><br />
+</dt>
+<dd>
+<code>'Default'</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_smallsetupperbound"><code>smallSetUpperBound</code></a></strong><br />
+</dt>
+<dd>
+<code>0</code>
+(This and the next four options provide flexible control for run-time
+details such as what record syntax to use when returning records. See
+sections
+3.2.2.1.4 (<strong>Small-set-element-set-names and
+Medium-set-element-set-names</strong>)
+and
+3.2.2.1.6 (<strong>Small-set-upper-bound, Large-set-lower-bound, and
+Medium-set-present-number</strong>)
+of the Z39.50 standard itself for details.)
+</dd>
+<p></p>
+<dt><strong><a name="item_largesetlowerbound"><code>largeSetLowerBound</code></a></strong><br />
+</dt>
+<dd>
+<code>1</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_mediumsetpresentnumber"><code>mediumSetPresentNumber</code></a></strong><br />
+</dt>
+<dd>
+<code>0</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_smallsetelementsetname"><code>smallSetElementSetName</code></a></strong><br />
+</dt>
+<dd>
+<code>'f'</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_mediumsetelementsetname"><code>mediumSetElementSetName</code></a></strong><br />
+</dt>
+<dd>
+<code>'b'</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_preferredrecordsyntax"><code>preferredRecordSyntax</code></a></strong><br />
+</dt>
+<dd>
+<code>'GRS-1'</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_responseposition"><code>responsePosition</code></a></strong><br />
+</dt>
+<dd>
+<code>1</code>
+(Indicates the one-based position of the start term in the set of
+terms returned from a scan.)
+</dd>
+<p></p>
+<dt><strong><a name="item_stepsize"><code>stepSize</code></a></strong><br />
+</dt>
+<dd>
+<code>0</code>
+(Indicates the number of terms between each of the terms returned from
+a scan.)
+</dd>
+<p></p>
+<dt><strong><a name="item_numberofentries"><code>numberOfEntries</code></a></strong><br />
+</dt>
+<dd>
+<code>20</code>
+(Indicates the number of terms to return from a scan.)
+</dd>
+<p></p>
+<dt><strong><a name="item_elementsetname"><code>elementSetName</code></a></strong><br />
+</dt>
+<dd>
+<code>'b'</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_namedresultsets"><code>namedResultSets</code></a></strong><br />
+</dt>
+<dd>
+<code>1</code> indicating boolean true. This option tells the client to use a
+new result set name for each new result set generated, so that old
+<code>ResultSet</code> objects remain valid. For the benefit of old, broken
+servers, this option may be set to 0, indicating that same result-set
+name, <code>default</code>, should be used for each search, so that each search
+invalidates all existing <code>ResultSet</code>s.
+</dd>
+<p></p></dl>
+<p>Any other option's value is undefined.</p>
+<p>
+</p>
+<hr />
+<h1><a name="asynchronous_mode">ASYNCHRONOUS MODE</a></h1>
+<p>I don't propose to discuss this at the moment, since I think it's more
+important to get the Tutorial out there with the synchronous stuff in
+place than to write the asynchronous stuff. I'll do it soon, honest.
+In the mean time, let me be clear: the asynchronous code itself is
+done and works (the synchronous interface is merely a thin layer on
+top of it) - it's only the <em>documentation</em> that's not yet here.</p>
+<p><strong>### Note to self - write this section!</strong></p>
+<p>
+</p>
+<hr />
+<h1><a name="now_what">NOW WHAT?</a></h1>
+<p>This tutorial is only an overview of what can be done with the
+<code>Net::Z3950</code> module. If you need more information that it provides,
+then you need to read the more technical documentation on the
+individual classes that make up the module -
+<code>Net::Z3950</code> itself,
+<code>Net::Z3950::Manager</code>,
+<code>Net::Z3950::Connection</code>,
+<code>Net::Z3950::ResultSet</code> and
+<code>Net::Z3950::Record</code>.</p>
+<p>
+</p>
+<hr />
+<h1><a name="author">AUTHOR</a></h1>
+<p>Mike Taylor <<a href="mailto:mike at indexdata.com">mike at indexdata.com</a>></p>
+<p>First version Sunday 28th January 2001.</p>
+
+</body>
+
+</html>
Added: packages/libnet-z3950-perl/trunk/doc/html/Z3950/APDU.html
===================================================================
--- packages/libnet-z3950-perl/trunk/doc/html/Z3950/APDU.html 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/doc/html/Z3950/APDU.html 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,448 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Net::Z3950::APDU - Read-only objects representing decoded Z39.50 APDUs</title>
+<link rev="made" href="mailto:root at localhost" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#subclasses">SUBCLASSES</a></li>
+ <ul>
+
+ <li><a href="#net__z3950__apdu__initresponse">Net::Z3950::APDU::InitResponse</a></li>
+ <li><a href="#net__z3950__apdu__searchresponse">Net::Z3950::APDU::SearchResponse</a></li>
+ <li><a href="#net__z3950__apdu__scanresponse">Net::Z3950::APDU::ScanResponse</a></li>
+ <li><a href="#net__z3950__apdu__presentresponse">Net::Z3950::APDU::PresentResponse</a></li>
+ <li><a href="#net__z3950__apdu__deletersresponse">Net::Z3950::APDU::DeleteRSResponse</a></li>
+ <li><a href="#net__z3950__apdu__close">Net::Z3950::APDU::Close</a></li>
+ <li><a href="#net__z3950__apdu__nameplusrecordlist">Net::Z3950::APDU::NamePlusRecordList</a></li>
+ <li><a href="#net__z3950__apdu__nameplusrecord">Net::Z3950::APDU::NamePlusRecord</a></li>
+ <li><a href="#net__z3950__apdu__sutrs__net__z3950__apdu__usmarc__net__z3950__apdu__ukmarc__net__z3950__apdu__normarc__net__z3950__apdu__librismarc__net__z3950__apdu__danmarc__net__z3950__apdu__unimarc__net__z3950__apdu__mab">Net::Z3950::APDU::SUTRS, Net::Z3950::APDU::USMARC, Net::Z3950::APDU::UKMARC, Net::Z3950::APDU::NORMARC, Net::Z3950::APDU::LIBRISMARC, Net::Z3950::APDU::DANMARC, Net::Z3950::APDU::UNIMARC, Net::Z3950::APDU::MAB</a></li>
+ <li><a href="#net__z3950__apdu__taggedelement_">Net::Z3950::APDU::TaggedElement;</a></li>
+ <li><a href="#net__z3950__apdu__elementdata">Net::Z3950::APDU::ElementData</a></li>
+ <li><a href="#net__z3950__apdu__holdingsdata">Net::Z3950::APDU::HoldingsData</a></li>
+ <li><a href="#net__z3950__apdu__holdingsandcirc">Net::Z3950::APDU::HoldingsAndCirc</a></li>
+ <li><a href="#net__z3950__apdu__volumes">Net::Z3950::APDU::Volumes</a></li>
+ <li><a href="#net__z3950__apdu__holdingsandcirc">Net::Z3950::APDU::HoldingsAndCirc</a></li>
+ <li><a href="#net__z3950__apdu__circulationdata">Net::Z3950::APDU::CirculationData</a></li>
+ <li><a href="#net__z3950__apdu__holdingsandcirc">Net::Z3950::APDU::HoldingsAndCirc</a></li>
+ <li><a href="#net__z3950__apdu__diagrecs">Net::Z3950::APDU::DiagRecs</a></li>
+ <li><a href="#net__z3950__apdu__defaultdiagformat_">Net::Z3950::APDU::DefaultDiagFormat;</a></li>
+ <li><a href="#net__z3950__apdu__oid">Net::Z3950::APDU::OID</a></li>
+ <li><a href="#net__z3950__apdu__listentries">Net::Z3950::APDU::ListEntries</a></li>
+ <li><a href="#net__z3950__apdu__entry">Net::Z3950::APDU::Entry</a></li>
+ <li><a href="#net__z3950__apdu__terminfo">Net::Z3950::APDU::TermInfo</a></li>
+ <li><a href="#net__z3950__apdu__term">Net::Z3950::APDU::Term</a></li>
+ <li><a href="#net__z3950__apdu__otherinformation">Net::Z3950::APDU::OtherInformation</a></li>
+ <li><a href="#net__z3950__apdu__otherinformationunit">Net::Z3950::APDU::OtherInformationUnit</a></li>
+ <li><a href="#net__z3950__apdu__searchinforeport">Net::Z3950::APDU::SearchInfoReport</a></li>
+ <li><a href="#net__z3950__apdu__searchinforeport_s">Net::Z3950::APDU::SearchInfoReport_s</a></li>
+ <li><a href="#net__z3950__apdu__queryexpression">Net::Z3950::APDU::QueryExpression</a></li>
+ <li><a href="#net__z3950__apdu__queryexpressionterm">Net::Z3950::APDU::QueryExpressionTerm</a></li>
+ </ul>
+
+ <li><a href="#author">AUTHOR</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Net::Z3950::APDU - Read-only objects representing decoded Z39.50 APDUs</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<p><em>You probably shouldn't be reading this!</em></p>
+<pre>
+ package Net::Z3950::APDU::SomeSpecificSortOfAPDU;
+ use Net::Z3950::APDU;
+ @ISA = qw(Net::Z3950::APDU);
+ @FIELDS = qw(names of APDU fields);</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>This class provides a trivial base for the various read-only APDUs
+implemented as a part of the Net::Z3950 module. Its role is simply to
+supply named methods providing read-only access to the same-named
+fields. The set of fields is specified by the derived class's
+package-global <code>@FIELDS</code> array.</p>
+<p><em>You don't need to understand or use this class in order to use the
+Net::Z3950 module. It's purely an implementation detail. In fact, I
+probably should never even have written this documentation. Forget I
+said anything. Go and read the next section.</em></p>
+<p>
+</p>
+<hr />
+<h1><a name="subclasses">SUBCLASSES</a></h1>
+<p>The following classes are all trivial derivations of <code>Net::Z3950::APDU</code>,
+and represent specific types of APDU. Each such class is
+characterised by the set of data-access methods it supplies: these are
+listed below.</p>
+<p>Each method takes no arguments, and returns the information implied by
+its name. See the relevant sections of the Z39.50 Standard for
+information on the interpretation of this information - for example,
+section 3.2.1 (Initialization Facility) describes the elements of the
+<code>Net::Z3950::APDU::InitResponse</code> class.</p>
+<p><em>Actually, you don't need to understand or use any of these classes
+either: they're used internally in the implementation, so this
+documentation is provided as a service to those who will further
+develop this module in the future.</em></p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__initresponse">Net::Z3950::APDU::InitResponse</a></h2>
+<pre>
+ referenceId()
+ preferredMessageSize()
+ maximumRecordSize()
+ result()
+ implementationId()
+ implementationName()
+ implementationVersion()</pre>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__searchresponse">Net::Z3950::APDU::SearchResponse</a></h2>
+<pre>
+ referenceId()
+ resultCount()
+ numberOfRecordsReturned()
+ nextResultSetPosition()
+ searchStatus()
+ resultSetStatus()
+ presentStatus()
+ records()
+ additionalSearchInfo()</pre>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__scanresponse">Net::Z3950::APDU::ScanResponse</a></h2>
+<pre>
+ referenceId()
+ stepSize()
+ scanStatus()
+ numberOfEntriesReturned()
+ positionOfTerm()
+ entries()
+ diag()</pre>
+<p>The <code>diag()</code> method should be consulted when <code>scanStatus()</code> returns
+6, indicating failure; otherwise, <code>entries()</code> may be consulted.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__presentresponse">Net::Z3950::APDU::PresentResponse</a></h2>
+<pre>
+ referenceId()
+ numberOfRecordsReturned()
+ nextResultSetPosition()
+ presentStatus()
+ records()</pre>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__deletersresponse">Net::Z3950::APDU::DeleteRSResponse</a></h2>
+<pre>
+ referenceId()
+ deleteOperationStatus()</pre>
+<p>(We don't bother to decode the rest of this APDU at the moment, since
+I bet everyone calls <code>Net::Z3950::ResultSet::delete()</code> in void
+context. If anyone wants more information out of it, we can wire it
+through.)</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__close">Net::Z3950::APDU::Close</a></h2>
+<pre>
+ referenceId()
+ closeReason()
+ diagnosticInformation()</pre>
+<p>In addition, this class provides a method of no arguments,
+<code>as_text()</code>, which returns a human-readable string describing the
+reason for the close.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__nameplusrecordlist">Net::Z3950::APDU::NamePlusRecordList</a></h2>
+<p>No methods - just treat as a reference to an array of
+<code>Net::Z3950::APDU::NamePlusRecord</code></p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__nameplusrecord">Net::Z3950::APDU::NamePlusRecord</a></h2>
+<pre>
+ databaseName()
+ which()
+ databaseRecord()
+ surrogateDiagnostic()
+ startingFragment()
+ intermediateFragment()
+ finalFragment()</pre>
+<p>Only one of the last five methods will return anything - you can find
+out which one by inspecting the return value of the <code>which()</code> method,
+which always takes one of the following values:</p>
+<ul>
+<li></li>
+Net::Z3950::NamePlusRecord::DatabaseRecord
+<p></p>
+<li></li>
+Net::Z3950::NamePlusRecord::SurrogateDiagnostic
+<p></p>
+<li></li>
+Net::Z3950::NamePlusRecord::StartingFragment
+<p></p>
+<li></li>
+Net::Z3950::NamePlusRecord::IntermediateFragment
+<p></p>
+<li></li>
+Net::Z3950::NamePlusRecord::FinalFragment
+<p></p></ul>
+<p>When <code>which()</code> is <code>Net::Z3950::NamePlusRecord::DatabaseRecord</code>, the
+object returned from the <code>databaseRecord()</code> method will be a decoded
+Z39.50 EXTERNAL. Its type may be any of the following (and may be
+tested using <code>$rec->isa('Net::Z3950::Record::Whatever')</code> if necessary.)</p>
+<ul>
+<li></li>
+Net::Z3950::Record::SUTRS
+<p></p>
+<li></li>
+Net::Z3950::Record::GRS1
+<p></p>
+<li></li>
+Net::Z3950::Record::USMARC and
+similarly, Net::Z3950::Record::UKMARC, Net::Z3950::Record::NORMARC, <em>etc</em>.
+<p></p>
+<li></li>
+Net::Z3950::Record::XML
+<p></p>
+<li></li>
+Net::Z3950::Record::HTML
+<p></p>
+<li></li>
+Net::Z3950::Record::OPAC
+<p><em>### others, not yet supported</em></p>
+<p></p></ul>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__sutrs__net__z3950__apdu__usmarc__net__z3950__apdu__ukmarc__net__z3950__apdu__normarc__net__z3950__apdu__librismarc__net__z3950__apdu__danmarc__net__z3950__apdu__unimarc__net__z3950__apdu__mab">Net::Z3950::APDU::SUTRS, Net::Z3950::APDU::USMARC, Net::Z3950::APDU::UKMARC, Net::Z3950::APDU::NORMARC, Net::Z3950::APDU::LIBRISMARC, Net::Z3950::APDU::DANMARC, Net::Z3950::APDU::UNIMARC, Net::Z3950::APDU::MAB</a></h2>
+<p>No methods - just treat as an opaque chunk of data.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__taggedelement_">Net::Z3950::APDU::TaggedElement;</a></h2>
+<pre>
+ tagType()
+ tagValue()
+ tagOccurrence()
+ content()</pre>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__elementdata">Net::Z3950::APDU::ElementData</a></h2>
+<pre>
+ which()
+ numeric()
+ string()
+ oid()
+ subtree()</pre>
+<p>Only one of the last four methods will return anything - you can find
+out which one by inspecting the return value of the <code>which()</code> method,
+which always takes one of the following values:</p>
+<ul>
+<li></li>
+Net::Z3950::ElementData::Numeric
+<p></p>
+<li></li>
+Net::Z3950::ElementData::String
+<p></p>
+<li></li>
+Net::Z3950::ElementData::OID
+<p></p>
+<li></li>
+Net::Z3950::ElementData::Subtree
+<p></p>
+<li></li>
+<em>### others, not yet supported</em>
+<p></p></ul>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__holdingsdata">Net::Z3950::APDU::HoldingsData</a></h2>
+<p>No methods - just treat as a reference to an array of objects, where
+each object is either an MARC holdings record (of type
+<code>Net::Z3950::Record::USMARC</code> or similar) or a
+<code>Net::Z3950::APDU::HoldingsAndCirc</code></p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__holdingsandcirc">Net::Z3950::APDU::HoldingsAndCirc</a></h2>
+<pre>
+ typeOfRecord()
+ encodingLevel()
+ format()
+ receiptAcqStatus()
+ generalRetention()
+ completeness()
+ dateOfReport()
+ nucCode()
+ localLocation()
+ shelvingLocation()
+ callNumber()
+ shelvingData()
+ copyNumber()
+ publicNote()
+ reproductionNote()
+ termsUseRepro()
+ enumAndChron()
+ volumes()
+ circulationData()</pre>
+<p>All but the last two of these have string values, although not
+necessarily human-readable strings. <code>volumes()</code> returns a
+<code>Net::Z3950::APDU::Volumes</code> object (note the plural in the
+type-name), and <code>circulationData()</code> a
+<code>Net::Z3950::APDU::CirculationData</code>.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__volumes">Net::Z3950::APDU::Volumes</a></h2>
+<p>No methods - just treat as a reference to an array of
+<code>Net::Z3950::APDU::Volume</code>
+objects.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__holdingsandcirc">Net::Z3950::APDU::HoldingsAndCirc</a></h2>
+<pre>
+ enumeration()
+ chronology()
+ enumAndChron()</pre>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__circulationdata">Net::Z3950::APDU::CirculationData</a></h2>
+<p>No methods - just treat as a reference to an array of
+<code>Net::Z3950::APDU::CircRecord</code>
+objects.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__holdingsandcirc">Net::Z3950::APDU::HoldingsAndCirc</a></h2>
+<pre>
+ availableNow()
+ availablityDate()
+ availableThru()
+ restrictions()
+ itemId()
+ renewable()
+ onHold()
+ enumAndChron()
+ midspine()
+ temporaryLocation()</pre>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__diagrecs">Net::Z3950::APDU::DiagRecs</a></h2>
+<p>No methods - just treat as a reference to an array of object
+references. The objects will typically be of class
+<code>Net::Z3950::APDU::DefaultDiagFormat</code>, but careful callers will check
+this, since any kind of EXTERNAL may be provided instead.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__defaultdiagformat_">Net::Z3950::APDU::DefaultDiagFormat;</a></h2>
+<pre>
+ diagnosticSetId()
+ condition()
+ addinfo()</pre>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__oid">Net::Z3950::APDU::OID</a></h2>
+<p><strong>No longer exists.</strong>
+Previously this class had no methods - calling code just treated it
+as a reference to an array of integers. However, since the only thing
+anyone (including <code>Net::Z3950::Record::GRS1::render()</code>)
+ever did with it was smush it up into a string with</p>
+<pre>
+ join('.', @$oidRef)</pre>
+<p>we now just return the dot-separated OID string
+<em>not blessed into any class</em>
+(because scalars can't be blessed - only <em>references</em> to scalars,
+and we don't want the extra useless level of indirection).</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__listentries">Net::Z3950::APDU::ListEntries</a></h2>
+<p>No methods - just treat as a reference to an array of
+<code>Net::Z3950::APDU::Entry</code></p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__entry">Net::Z3950::APDU::Entry</a></h2>
+<pre>
+ termInfo()
+ surrogateDiagnostic()</pre>
+<p>Usually, <code>termInfo()</code> returns a scanned term. When it returns an
+undefined value, consult <surrogateDiagnostic()> to find out why.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__terminfo">Net::Z3950::APDU::TermInfo</a></h2>
+<pre>
+ term()
+ globalOccurrences()</pre>
+<p><em>### Lots more to come here, including displayTerm</em></p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__term">Net::Z3950::APDU::Term</a></h2>
+<pre>
+ general()
+ numeric()
+ characterString()
+ oid()
+ dateTime()
+ external()
+ integerAndUnit()
+ null()</pre>
+<p>At present only ``general'' terms are supported. The value of such a
+term may be obtained by calling <general()>. Terms of other types can
+not be obtained.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__otherinformation">Net::Z3950::APDU::OtherInformation</a></h2>
+<p>No methods - just treat as a reference to an array of
+<code>Net::Z3950::APDU::OtherInformationUnit</code></p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__otherinformationunit">Net::Z3950::APDU::OtherInformationUnit</a></h2>
+<pre>
+ which()
+ characterInfo()
+ binaryInfo()
+ externallyDefinedInfo
+ oid()</pre>
+<p>At present only ``externallyDefinedInfo'' units are supported.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__searchinforeport">Net::Z3950::APDU::SearchInfoReport</a></h2>
+<p>No methods - just treat as a reference to an array of
+<code>Net::Z3950::APDU::SearchInfoReport_s</code></p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__searchinforeport_s">Net::Z3950::APDU::SearchInfoReport_s</a></h2>
+<pre>
+ fullQuery()
+ subqueryExpression()
+ subqueryCount()</pre>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__queryexpression">Net::Z3950::APDU::QueryExpression</a></h2>
+<pre>
+ which()
+ term()
+ query()</pre>
+<p>At present only ``term'' query expressions are supported.</p>
+<p>
+</p>
+<h2><a name="net__z3950__apdu__queryexpressionterm">Net::Z3950::APDU::QueryExpressionTerm</a></h2>
+<pre>
+ queryTerm()</pre>
+<p>
+</p>
+<hr />
+<h1><a name="author">AUTHOR</a></h1>
+<p>Mike Taylor <<a href="mailto:mike at indexdata.com">mike at indexdata.com</a>></p>
+<p>First version Saturday 27th May 2000.</p>
+
+</body>
+
+</html>
Added: packages/libnet-z3950-perl/trunk/doc/html/Z3950/Connection.html
===================================================================
--- packages/libnet-z3950-perl/trunk/doc/html/Z3950/Connection.html 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/doc/html/Z3950/Connection.html 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,358 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Net::Z3950::Connection - Connection to a Z39.50 server, with request queue</title>
+<link rev="made" href="mailto:root at localhost" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#methods">METHODS</a></li>
+ <ul>
+
+ <li><a href="#new__"><code>new()</code></a></li>
+ <li><a href="#option__"><code>option()</code></a></li>
+ <li><a href="#manager__"><code>manager()</code></a></li>
+ <li><a href="#startsearch__"><code>startSearch()</code></a></li>
+ <li><a href="#startscan__"><code>startScan()</code></a></li>
+ <li><a href="#search__"><code>search()</code></a></li>
+ <li><a href="#scan__"><code>scan()</code></a></li>
+ <li><a href="#op__"><code>op()</code></a></li>
+ <li><a href="#errcode____addinfo____errop____errmsg__">errcode(), addinfo(), errop(), <code>errmsg()</code></a></li>
+ <li><a href="#initresponse__"><code>initResponse()</code></a></li>
+ <li><a href="#searchresponse____resultset__">searchResponse(), <code>resultSet()</code></a></li>
+ <li><a href="#scanresponse____scanset__">scanResponse(), <code>scanSet()</code></a></li>
+ <li><a href="#resultsets__"><code>resultSets()</code></a></li>
+ <li><a href="#name__"><code>name()</code></a></li>
+ <li><a href="#close__"><code>close()</code></a></li>
+ </ul>
+
+ <li><a href="#author">AUTHOR</a></li>
+ <li><a href="#see_also">SEE ALSO</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Net::Z3950::Connection - Connection to a Z39.50 server, with request queue</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ $conn = new Net::Z3950::Connection($hostname, $port);
+ $rs = $conn->search('au=kernighan and su=unix');
+ $sr = $conn->scan('au=kernighan and su=unix');
+ # or
+ $mgr = $conn->manager();
+ $conn = $mgr->wait();
+ if ($mgr->failed()) {
+ die "error " . $conn->errcode() .
+ "( " . $conn->addinfo() . ")" .
+ " in " . Net::Z3950::opstr($conn->errop());
+ }</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>A connection object represents an established connection to a
+particular server on a particular port, together with options such as
+the default database in which to search. It maintains a queue of
+outstanding requests (searches executed against it, fetches executed
+against result sets instantiated against it) <em>etc.</em></p>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<p>
+</p>
+<h2><a name="new__"><code>new()</code></a></h2>
+<pre>
+ $conn = new Net::Z3950::Connection($mgr, $host, $port);
+ $conn = new Net::Z3950::Connection($host, $port);
+ $conn = new Net::Z3950::Connection($mgr, "unix", $path);
+ $conn = new Net::Z3950::Connection("unix", $path);</pre>
+<p>Creates and returns a new connection, under the control of the manager
+<em>$mgr</em>, to the server on the specified <em>$host</em> and <em>$port</em>. If the
+<em>$port</em> argument is omitted, the <code>z3950</code> service is used; if this is
+not defined, port 210 is used.</p>
+<p>The manager argument may be omitted, in which
+case, the connection is created under the control of a
+``default manager'', a reference to which may be subsequently
+retrieved with the <code>manager()</code> method. Multiple connections made
+with no explicitly-specified manager in this way will all share the
+same implicit manager. The default manager is initially in
+synchronous mode. If you don't understand what this paragraph is on
+about, you should feel free to ignore it.</p>
+<p>Unix-domain socket connections can be made by specifying <code>unix</code> as
+the hostname and the path to the socket file as the port.</p>
+<p>If the connection is created in synchronous mode, (or, if the
+constructor call doesn't specify a mode, if the manager controlling
+the new connection is synchronous), then the constructor does not
+return until either the connection is forged or an error occurs in
+trying to do so. (In the latter case, error information is stored in
+the manager structure.) If the connection is asynchronous, then the
+new object is created and returned before the connection is forged;
+this will happen in parallel with subsequent actions.</p>
+<p><em>This is a lie: connecting is always done synchronously.</em></p>
+<p>If a connection cannot be forged, then <code>$!</code> contains an error code
+indicating what went wrong: this may be one of the usual system error
+codes such as ECONNREFUSED (if there is no server running at the
+specified address); alternatively, it may be set to the distinguished
+value -1 if the TCP/IP connection was correctly forged, but the Z39.50
+<code>Init</code> failed.</p>
+<p>Any of the standard options (including asynchronous
+mode) may be specified as additional arguments. Specifically:</p>
+<pre>
+ $conn = new Net::Z3950::Connection($mgr, $host, $port, async => 1);</pre>
+<p>Works as expected.</p>
+<p>
+</p>
+<h2><a name="option__"><code>option()</code></a></h2>
+<pre>
+ $value = $conn->option($type);
+ $value = $conn->option($type, $newval);</pre>
+<p>Returns <em>$conn</em>'s value of the standard option <em>$type</em>, as
+registered in <em>$conn</em> itself, in the manager which controls it, or in
+the global defaults.</p>
+<p>If <em>$newval</em> is specified, then it is set as the new value of that
+option in <em>$conn</em>, and the option's old value is returned.</p>
+<p>
+</p>
+<h2><a name="manager__"><code>manager()</code></a></h2>
+<pre>
+ $mgr = $conn->manager();</pre>
+<p>Returns a reference to the manager controlling <em>$conn</em>. If <em>$conn</em>
+was created with an explicit manager, then this method will always
+return that function; otherwise, it returns a reference to the single
+global ``default manager'' shared by all other connections.</p>
+<p>
+</p>
+<h2><a name="startsearch__"><code>startSearch()</code></a></h2>
+<pre>
+ $conn->startSearch($srch);
+ $conn->startSearch(-ccl => 'au=kernighan and su=unix');
+ $conn->startSearch(-prefix => '@and @attr 1=1 kernighan @attr 1=21 unix');
+ $conn->startSearch('@and @attr 1=1 kernighan @attr 1=21 unix');</pre>
+<p>Inititiates a new search against the Z39.50 server to which <em>$conn</em>
+is connected. Since this can never fail (:-), it <code>die()s</code> if
+anything goes wrong. But that will never happen. (``Surely the odds
+of that happening are million to one, doctor?'')</p>
+<p>The query itself can be specified in a variety of ways:</p>
+<ul>
+<li></li>
+A <code>Net::Z3950::Query</code> object may be passed in.
+<p></p>
+<li></li>
+A query-type option may be passed in, together with the query string
+itself as its argument. Currently recognised query types are <code>-ccl</code>
+(using the standard CCL query syntax, interpreted by the server),
+<code>-ccl2rpn</code> (CCL query compiled by the client into a type-1 query),
+<code>-prefix</code> (using Index Data's prefix query notation, described at
+<a href="http://indexdata.dk/yaz/doc/tools.php#PQF">http://indexdata.dk/yaz/doc/tools.php#PQF</a> )
+and <code>-cql</code> (passing a CQL query straight through to the server).
+<p></p>
+<li></li>
+A query string alone may be passed in. In this case, it is
+interpreted according to the query type previously established as a
+default for <em>$conn</em> or its manager.
+<p></p></ul>
+<p>The various query types are described in more detail in the
+documentation of the <code>Net::Z3950::Query</code> class.</p>
+<p><em>### The Query class does not yet, and might never, exist.</em></p>
+<p>Some broken Z39.50 server will fault a search but not provide any
+diagnostic records. The correct fix for this problem is of course to
+poke the providers of those servers in the back of the knee with a
+teaspoon until they fix their products. But since this is not always
+practical, <code>Net::Z3950</code> provides a dummy diagnostic record in this
+case, with error-code 3 (``unsupported search'') and additional
+information set to ``no diagnostic records supplied by server''.</p>
+<p>
+</p>
+<h2><a name="startscan__"><code>startScan()</code></a></h2>
+<pre>
+ $conn->startScan($scan);
+ $conn->startScan(-prefix => '@attr 1=5 programming');
+ $conn->startScan('@attr 1=5 programming');</pre>
+<p>Executes a scan against the Z39.50 server to which <em>$conn</em> is
+connected. The scan parameters are represented by a query which is
+analysed for the term itself and the access-point in which it should
+occur. This query can be specified in the same ways as for
+<code>startSearch()</code>.</p>
+<p>
+</p>
+<h2><a name="search__"><code>search()</code></a></h2>
+<pre>
+ $rs = $conn->search($srch);</pre>
+<p>This method performs a blocking search, returning a reference
+to the result set generated by the server. It takes the same
+arguments as <code>startSearch()</code></p>
+<p>
+</p>
+<h2><a name="scan__"><code>scan()</code></a></h2>
+<pre>
+ $sr = $conn->scan($scan);</pre>
+<p>This method performs a blocking scan, returning a reference
+to the scan result generated by the server. It takes the same
+arguments as <code>startScan()</code></p>
+<p>The returned structure is a <code>Net::Z3950::APDU::ScanResponse</code> which
+can be pulled apart by inspection. That may not be the nicest
+possible interface.</p>
+<p>
+</p>
+<h2><a name="op__"><code>op()</code></a></h2>
+<pre>
+ op = $conn->op();
+ if (op == Net::Z3950::Op::Search) { # ...</pre>
+<p>When a connection has been returned from the <code>Net::Z3950::Manager</code> class's
+<code>wait()</code> method, it's known that <em>something</em> has happened to it.
+This method may then be called to find out what. It returns one of
+the following values:</p>
+<dl>
+<dt><strong><a name="item_net_3a_3az3950_3a_3aop_3a_3aerror"><code>Net::Z3950::Op::Error</code></a></strong><br />
+</dt>
+<dd>
+An error occurred. The details may be obtained via the <code>errcode()</code>,
+<code>addinfo()</code> and <code>errop()</code> methods described below.
+</dd>
+<p></p>
+<dt><strong><a name="item_net_3a_3az3950_3a_3aop_3a_3ainit"><code>Net::Z3950::Op::Init</code></a></strong><br />
+</dt>
+<dd>
+An init response was received. The response object may be obtained
+via the <code>initResponse()</code> method described below.
+</dd>
+<p></p>
+<dt><strong><a name="item_net_3a_3az3950_3a_3aop_3a_3asearch"><code>Net::Z3950::Op::Search</code></a></strong><br />
+</dt>
+<dd>
+A search response was received. The result set may be obtained via
+the <code>resultSet()</code> method described below, or the raw APDU object may
+be obtained via <code>searchResponse()</code>.
+</dd>
+<p></p>
+<dt><strong><a name="item_net_3a_3az3950_3a_3aop_3a_3aget"><code>Net::Z3950::Op::Get</code></a></strong><br />
+</dt>
+<dd>
+One or more result-set records have become available. They may be
+obtained via the <code>record()</code> method of the appropriate result set.
+</dd>
+<p></p>
+<dt><strong><a name="item_net_3a_3az3950_3a_3aop_3a_3ascan"><code>Net::Z3950::Op::Scan</code></a></strong><br />
+</dt>
+<dd>
+A scan response was received. The scan-set may be obtained via the
+<code>scanSet()</code> method described below, or the raw APDU object may be
+obtained via <code>scanResponse()</code>.
+</dd>
+<p></p></dl>
+<p>
+</p>
+<h2><a name="errcode____addinfo____errop____errmsg__">errcode(), addinfo(), errop(), <code>errmsg()</code></a></h2>
+<pre>
+ if ($conn->op() == Net::Z3950::Op::Error) {
+ print "error number: ", $conn->errcode(), "\n";
+ print "error message: ", $conn->errmsg(), "\n";
+ print "additional info: ", $conn->errcode(), "\n";
+ print "in function: ", Net::Z3950::opstr($conn->errop()), "\n";
+ }</pre>
+<p>When an error is known to have occurred on a connection, the error
+code (from the BIB-1 diagnosic set) can be retrieved via the
+<code>errcode()</code> method, any additional information via the <code>addinfo()</code>
+method, and the operation that was being attempted when the error
+occurred via the <code>errop()</code> method. (The error operation returned
+takes one of the values that may be returned from the <code>op()</code> method.)</p>
+<p>The meanings of the BIB-1 diagnostics are described at on the Z39.50
+Maintenance Agency web-site at
+<a href="http://lcweb.loc.gov/z3950/agency/defns/bib1diag.html">http://lcweb.loc.gov/z3950/agency/defns/bib1diag.html</a></p>
+<p>As a convenience, <code>$conn-</code>errmsg()> is equivalent to
+<code>Net::Z3950::errstr($conn-</code>errcode())>.</p>
+<p>
+</p>
+<h2><a name="initresponse__"><code>initResponse()</code></a></h2>
+<pre>
+ if ($op == Net::Z3950::Op::Init) {
+ $rs = $conn->initResponse();</pre>
+<p>When a connection is known to have received an init response, the
+response may be accessed via the connection's <code>initResponse()</code>
+method.</p>
+<p>
+</p>
+<h2><a name="searchresponse____resultset__">searchResponse(), <code>resultSet()</code></a></h2>
+<pre>
+ if ($op == Net::Z3950::Op::Search) {
+ $sr = $conn->searchResponse();
+ $rs = $conn->resultSet();</pre>
+<p>When a connection is known to have received a search response, the
+response may be accessed via the connection's <code>searchResponse()</code>, and
+the search result may be accessed via the connection's <code>resultSet()</code>
+method.</p>
+<p>
+</p>
+<h2><a name="scanresponse____scanset__">scanResponse(), <code>scanSet()</code></a></h2>
+<pre>
+ if ($op == Net::Z3950::Op::Scan) {
+ $sr = $conn->scanResponse();
+ $ss = $conn->scanSet();</pre>
+<p>When a connection is known to have received a scan response, the
+response may be accessed via the connection's <code>scanResponse()</code>, and
+the scan-set may be accessed via the connection's <code>scanSet()</code>
+method.</p>
+<p>
+</p>
+<h2><a name="resultsets__"><code>resultSets()</code></a></h2>
+<pre>
+ @rs = $conn->resultSets();</pre>
+<p>Returns a list of all the result sets that have been created across
+the connection <em>$conn</em> and have not subsequently been deleted.</p>
+<p>
+</p>
+<h2><a name="name__"><code>name()</code></a></h2>
+<pre>
+ print $conn->name();</pre>
+<p>Returns a short string which can be used as the connection's ``name'' in
+text output.</p>
+<p>
+</p>
+<h2><a name="close__"><code>close()</code></a></h2>
+<pre>
+ $conn->close();</pre>
+<p>This lets the <code>Net::Z3950</code> module know that you no longer want to use
+<code>$conn</code> so it can be closed. It would be nice if this could be done
+implicitly when <code>$conn</code> goes out of scope, as in:</p>
+<pre>
+ {
+ $conn = new Net::Z3950::Connection($host, $port);
+ $rs = $conn->search($query);
+ print "found ", $rs->size(), " records\n";
+ }</pre>
+<p>But in general this won't work, because <code>$conn</code> is not the only
+reference to the connection object: when it goes out of scope, the
+connection is not destroyed because its manager still holds a
+reference to it. So use <code>$conn-</code>close()> (just before the close
+brace in the example above) to let the connection know it's done with.</p>
+<p>
+</p>
+<hr />
+<h1><a name="author">AUTHOR</a></h1>
+<p>Mike Taylor <<a href="mailto:mike at indexdata.com">mike at indexdata.com</a>></p>
+<p>First version Tuesday 23rd May 2000.</p>
+<p>
+</p>
+<hr />
+<h1><a name="see_also">SEE ALSO</a></h1>
+<p><code>Net::Z3950::Query</code></p>
+
+</body>
+
+</html>
Added: packages/libnet-z3950-perl/trunk/doc/html/Z3950/Manager.html
===================================================================
--- packages/libnet-z3950-perl/trunk/doc/html/Z3950/Manager.html 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/doc/html/Z3950/Manager.html 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,152 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Net::Z3950::Manager - State manager for multiple Z39.50 connections.</title>
+<link rev="made" href="mailto:root at localhost" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#methods">METHODS</a></li>
+ <ul>
+
+ <li><a href="#new__"><code>new()</code></a></li>
+ <li><a href="#option__"><code>option()</code></a></li>
+ <li><a href="#connect__"><code>connect()</code></a></li>
+ <li><a href="#wait__"><code>wait()</code></a></li>
+ <li><a href="#connections__"><code>connections()</code></a></li>
+ <li><a href="#resultsets__"><code>resultSets()</code></a></li>
+ </ul>
+
+ <li><a href="#author">AUTHOR</a></li>
+ <li><a href="#see_also">SEE ALSO</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Net::Z3950::Manager - State manager for multiple Z39.50 connections.</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ $mgr = new Net::Z3950::Manager(async => 1);
+ $conn = $mgr->connect($hostname, $port);
+ # Set up some more connections, then:
+ while ($conn = $mgr->wait()) {
+ # Handle message on $conn
+ }</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>A manager object encapsulates the Net::Z3950 module's global state -
+preferences for search parsing, preferred record syntaxes, compiled
+configuration files, <em>etc.</em> - as well as a list of references to all
+the open connections. It main role is to handle multiplexing between
+the connections that are opened on it.</p>
+<p>We would normally expect there to be just one manager object in a
+program, but I suppose there's no reason why you shouldn't make more
+if you want.</p>
+<p>Simple programs - those which therefore have no requirement for
+multiplexing, perhaps because they connect only to a single server -
+do not need explicitly to create a manager at all: an anonymous
+manager is implicitly created along with the connection.</p>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<p>
+</p>
+<h2><a name="new__"><code>new()</code></a></h2>
+<pre>
+ $mgr = new Net::Z3950::Manager();</pre>
+<p>Creates and returns a new manager. Any of the standard options may be
+specified as arguments; in addition, the following manager-specific
+options are recognised:</p>
+<dl>
+<dt><strong><a name="item_async">async</a></strong><br />
+</dt>
+<dd>
+This is 0 (false) by default, and may be set to 1 (true). The mode
+affects various details of subsequent behaviour - for example, see the
+description of the <code>Net::Z3950::Connection</code> class's <code>new()</code> method.
+</dd>
+<p></p></dl>
+<p>
+</p>
+<h2><a name="option__"><code>option()</code></a></h2>
+<pre>
+ $value = $mgr->option($type);
+ $value = $mgr->option($type, $newval);</pre>
+<p>Returns <em>$mgr</em>'s value of the standard option <em>$type</em>, as registered
+in <em>$mgr</em> or in the global defaults.</p>
+<p>If <em>$newval</em> is specified, then it is set as the new value of that
+option in <em>$mgr</em>, and the option's old value is returned.</p>
+<p>
+</p>
+<h2><a name="connect__"><code>connect()</code></a></h2>
+<pre>
+ $conn = $mgr->connect($hostname, $port);</pre>
+<p>Creates a new connection under the control of the manager <em>$mgr</em>.
+The connection will be forged to the server on the specified <em>$port</em>
+of <$hostname>.</p>
+<p>Additional standard options may be specified after the <em>$port</em>
+argument.</p>
+<p>(This is simply a sugar function to <code>Net::Z3950::Connection-</code>new()>)</p>
+<p>
+</p>
+<h2><a name="wait__"><code>wait()</code></a></h2>
+<pre>
+ $conn = $mgr->wait();</pre>
+<p>Waits for an event to occur on one of the connections under the
+control of <em>$mgr</em>, yielding control to any other event handlers that
+may have been registered with the underlying event loop.</p>
+<p>When a suitable event occurs - typically, a response is received to an
+earlier INIT, SEARCH or PRESENT - the handle of the connection on
+which it occurred is returned: the handle can be further interrogated
+with its <code>op()</code> and related methods.</p>
+<p>If the wait times out (only possible if the manager's <code>timeout</code>
+option has been set), then <code>wait()</code> returns an undefined value.</p>
+<p>
+</p>
+<h2><a name="connections__"><code>connections()</code></a></h2>
+<pre>
+ @conn = $mgr->connections();</pre>
+<p>Returns a list of all the connections that have been opened under the
+control of the manager <em>$mgr</em> and have not subsequently been closed.</p>
+<p>
+</p>
+<h2><a name="resultsets__"><code>resultSets()</code></a></h2>
+<pre>
+ @rs = $mgr->resultSets();</pre>
+<p>Returns a list of all the result sets that have been created across
+the connections associated with the manager <em>$mgr</em> and have not
+subsequently been deleted.</p>
+<p>
+</p>
+<hr />
+<h1><a name="author">AUTHOR</a></h1>
+<p>Mike Taylor <<a href="mailto:mike at indexdata.com">mike at indexdata.com</a>></p>
+<p>First version Tuesday 23rd May 2000.</p>
+<p>
+</p>
+<hr />
+<h1><a name="see_also">SEE ALSO</a></h1>
+<p>List of standard options.</p>
+<p>Discussion of the Net::Z3950 module's use of the Event module.</p>
+
+</body>
+
+</html>
Added: packages/libnet-z3950-perl/trunk/doc/html/Z3950/Record.html
===================================================================
--- packages/libnet-z3950-perl/trunk/doc/html/Z3950/Record.html 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/doc/html/Z3950/Record.html 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,165 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Net::Z3950::Record - base class for records retrieved from a Z39.50 server</title>
+<link rev="made" href="mailto:root at localhost" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#methods">METHODS</a></li>
+ <ul>
+
+ <li><a href="#nfields__"><code>nfields()</code></a></li>
+ <li><a href="#render__"><code>render()</code></a></li>
+ <li><a href="#rawdata__"><code>rawdata()</code></a></li>
+ </ul>
+
+ <li><a href="#subclasses">SUBCLASSES</a></li>
+ <ul>
+
+ <li><a href="#net__z3950__record__sutrs">Net::Z3950::Record::SUTRS</a></li>
+ <li><a href="#net__z3950__record__grs1">Net::Z3950::Record::GRS1</a></li>
+ <li><a href="#net__z3950__record__usmarc__net__z3950__record__ukmarc__net__z3950__record__normarc__net__z3950__record__librismarc__net__z3950__record__danmarc__net__z3950__record__unimarc">Net::Z3950::Record::USMARC, Net::Z3950::Record::UKMARC, Net::Z3950::Record::NORMARC, Net::Z3950::Record::LIBRISMARC, Net::Z3950::Record::DANMARC, Net::Z3950::Record::UNIMARC</a></li>
+ <li><a href="#net__z3950__record__xml">Net::Z3950::Record::XML</a></li>
+ <li><a href="#net__z3950__record__html">Net::Z3950::Record::HTML</a></li>
+ <li><a href="#net__z3950__record__opac">Net::Z3950::Record::OPAC</a></li>
+ <li><a href="#net__z3950__record__mab">Net::Z3950::Record::MAB</a></li>
+ <li><a href="#____others__not_yet_supported">### others, not yet supported</a></li>
+ </ul>
+
+ <li><a href="#author">AUTHOR</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Net::Z3950::Record - base class for records retrieved from a Z39.50 server</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ $rs = $conn->resultSet();
+ $rec = $rs->record($n);
+ print $rec->render();</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>A Record object represents a record retrieved from a Z39.50 server.
+In fact, the <code>Net::Z3950::Record</code> class itself is never instantiated:
+instead, the Net::Z3950 module creates objects of subclasses such as
+<code>Net::Z3950::Record::SUTRS</code>, <code>Net::Z3950::Record::GRS1</code>,
+<code>Net::Z3950::Record::USMARC</code> and <code>Net::Z3950::Record::XML</code>.
+This class defines a common interface which must be supported by all
+such subclasses.</p>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<p>
+</p>
+<h2><a name="nfields__"><code>nfields()</code></a></h2>
+<pre>
+ $count = $rec->nfields();</pre>
+<p>Returns the number of fields in the record <em>$rec</em>.</p>
+<p>
+</p>
+<h2><a name="render__"><code>render()</code></a></h2>
+<pre>
+ print $rec->render();</pre>
+<p>Returns a human-readable string representing the content of the record
+<em>$rec</em> in a form appropriate to its specific type.</p>
+<p>
+</p>
+<h2><a name="rawdata__"><code>rawdata()</code></a></h2>
+<pre>
+ $raw = $rec->rawdata();</pre>
+<p>Returns the raw form of the data in the record, which will in general
+be different in form for different record syntaxes.</p>
+<p>
+</p>
+<hr />
+<h1><a name="subclasses">SUBCLASSES</a></h1>
+<p>
+</p>
+<h2><a name="net__z3950__record__sutrs">Net::Z3950::Record::SUTRS</a></h2>
+<p>Represents a a record using the Simple Unstructured Text Record
+Syntax (SUTRS) - a simple flat string containing the record's data in
+a form suitable for presentation to humans (so that the <code>render()</code>
+and <code>rawdata()</code> methods return the same thing.)</p>
+<p>See Appendix REC.2 (Simple Unstructured Text Record Syntax) of the
+Z39.50 Standard for more information.</p>
+<p>
+</p>
+<h2><a name="net__z3950__record__grs1">Net::Z3950::Record::GRS1</a></h2>
+<p>Represents a record using Generic Record Syntax 1 (GRS1) - a list of
+tagged fields where each tag is made up of a tag type and tag value,
+and each field may be of any type, including numeric, string, and
+recursively contained sub-record. Fields may also be annotated with
+metadata, variant information <em>etc.</em></p>
+<p>See Appendix REC.5 (Generic Record Syntax 1) of the Z39.50 Standard
+for more information.</p>
+<p>
+</p>
+<h2><a name="net__z3950__record__usmarc__net__z3950__record__ukmarc__net__z3950__record__normarc__net__z3950__record__librismarc__net__z3950__record__danmarc__net__z3950__record__unimarc">Net::Z3950::Record::USMARC, Net::Z3950::Record::UKMARC, Net::Z3950::Record::NORMARC, Net::Z3950::Record::LIBRISMARC, Net::Z3950::Record::DANMARC, Net::Z3950::Record::UNIMARC</a></h2>
+<p>Represents a record using the appropriate MARC (MAchine Readable
+Catalogue) format - binary formats used extensively in libraries.</p>
+<p>For further information on the MARC formats, see the Library of
+Congress Network Development and MARC Standards Office web page at
+<a href="http://lcweb.loc.gov/marc/">http://lcweb.loc.gov/marc/</a> and the MARC module in Ed Summers's
+directory at CPAN,
+<a href="http://cpan.valueclick.com/authors/id/E/ES/ESUMMERS/">http://cpan.valueclick.com/authors/id/E/ES/ESUMMERS/</a></p>
+<p>
+</p>
+<h2><a name="net__z3950__record__xml">Net::Z3950::Record::XML</a></h2>
+<p>Represents a a record using XML (Extended Markup Language), as defined
+by the W3C. Rendering is not currently defined: this module treats
+the record as a single opaque lump of data, to be parsed by other
+software.</p>
+<p>For more information about XML, see <a href="http://www.w3.org/XML/">http://www.w3.org/XML/</a></p>
+<p>
+</p>
+<h2><a name="net__z3950__record__html">Net::Z3950::Record::HTML</a></h2>
+<p>Represents a a record using HTML (HyperText Markup Language), as
+defined by the W3C. Rendering is not currently defined: this module
+treats the record as a single opaque lump of data, to be handled by
+other software.</p>
+<p>For more information about HTML, see <a href="http://www.w3.org/MarkUp/">http://www.w3.org/MarkUp/</a></p>
+<p>
+</p>
+<h2><a name="net__z3950__record__opac">Net::Z3950::Record::OPAC</a></h2>
+<p>Represents a a record using the OPAC (Online Public Access Catalogue)
+record syntax, as defined in Appendix 5 (REC) of the Z39.50 standard
+at <a href="http://lcweb.loc.gov/z3950/agency/asn1.html#RecordSyntax-opac">http://lcweb.loc.gov/z3950/agency/asn1.html#RecordSyntax-opac</a></p>
+<p>
+</p>
+<h2><a name="net__z3950__record__mab">Net::Z3950::Record::MAB</a></h2>
+<p>Represents a record using the MAB record syntax (Maschinelles
+Austauschformat fuer Bibliotheken, <a href="ftp://ftp.ddb.de/pub/mab/);">ftp://ftp.ddb.de/pub/mab/);</a> an
+interchange format defined by Die Deutsche Bibliothek (German National
+Library).</p>
+<p>
+</p>
+<h2><a name="____others__not_yet_supported">### others, not yet supported</a></h2>
+<p>
+</p>
+<hr />
+<h1><a name="author">AUTHOR</a></h1>
+<p>Mike Taylor <<a href="mailto:mike at indexdata.com">mike at indexdata.com</a>></p>
+<p>First version Sunday 4th May 2000.</p>
+
+</body>
+
+</html>
Added: packages/libnet-z3950-perl/trunk/doc/html/Z3950/ResultSet.html
===================================================================
--- packages/libnet-z3950-perl/trunk/doc/html/Z3950/ResultSet.html 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/doc/html/Z3950/ResultSet.html 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,191 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Net::Z3950::ResultSet - result set received in response to a Z39.50 search</title>
+<link rev="made" href="mailto:root at localhost" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#methods">METHODS</a></li>
+ <ul>
+
+ <li><a href="#size__"><code>size()</code></a></li>
+ <li><a href="#subquerycount__"><code>subqueryCount()</code></a></li>
+ <li><a href="#present__"><code>present()</code></a></li>
+ <li><a href="#record__"><code>record()</code></a></li>
+ <li><a href="#records__"><code>records()</code></a></li>
+ <li><a href="#delete__"><code>delete()</code></a></li>
+ <li><a href="#errcode____addinfo____errmsg__">errcode(), addinfo(), <code>errmsg()</code></a></li>
+ <li><a href="#option__"><code>option()</code></a></li>
+ </ul>
+
+ <li><a href="#author">AUTHOR</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Net::Z3950::ResultSet - result set received in response to a Z39.50 search</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ if ($conn->op() == Net::Z3950::Op::Search) {
+ $rs = $conn->resultSet();
+ $size = $rs->size();</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>A ResultSet object represents the set of records found by a Z39.50
+server in response to a search. At any given time, none, some or all
+of the records may have been physcially transferred to the client; a
+cache is maintained.</p>
+<p>Note that there is no constructor for this class (or at least, none
+that I'm going to tell you about :-) ResultSet objects are always
+created by the Net::Z3950 module itself, and are returned to the caller
+via the <code>Net::Z3950::Connection</code> class's <code>resultSet()</code> method.</p>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<p>
+</p>
+<h2><a name="size__"><code>size()</code></a></h2>
+<pre>
+ $nrecords = $rs->size();</pre>
+<p>Returns the number of records in the result set <em>$rs</em></p>
+<p>
+</p>
+<h2><a name="subquerycount__"><code>subqueryCount()</code></a></h2>
+<pre>
+ $subquery = $rs->subqueryCount();</pre>
+<p>Returns hit count of subquery terms as a hash reference containing
+(term, count) pairs, if the server returned this information. If the
+information is not available, an undefined value is returned.</p>
+<p>
+</p>
+<h2><a name="present__"><code>present()</code></a></h2>
+<pre>
+ $rs->present($start, $count) or die "failed: $rs->{errcode}\n";</pre>
+<p>Causes any records in the specified range that are not yet in the
+cache to be retrieved from the server. By calling this method before
+retrieving individual records with <code>record()</code>, you avoid sending lots
+of small requests for single records across the network. In
+asynchronous mode, <code>present()</code> just schedules the records for
+retrieval.</p>
+<p>Note that <code>$start</code> is indexed from 1.</p>
+<p>In synchronous mode, returns 1 if the records were successfully
+retrieved, 0 if an error occurred. In asynchronous mode, returns 1 if
+new requests were queued, 0 if all of the requested records had
+already been queued.</p>
+<p>
+</p>
+<h2><a name="record__"><code>record()</code></a></h2>
+<pre>
+ $rec = $rs->record($n);</pre>
+<p>Returns a reference to <em>$n</em>th record in the result set <em>$rs</em>, if the
+content of that record is known. Valid values of <em>$n</em> range from 1
+to the return value of the <code>size()</code> method.</p>
+<p>If the record is not available, an undefined value is returned, and
+diagnostic information made available via <em>$rs</em>'s <code>errcode()</code> and
+<code>addinfo()</code> methods.</p>
+<p>As a special case, when the connection is anychronous, the
+<code>errcode()</code> may be zero, indicating simply that the record has not
+yet been fetched from the server. In this case, the calling code
+should try again later. (How much later? As a rule of thumb, after
+it's done ``something else'', such as request another record or issue
+another search.) This can never happen in synchronous mode.</p>
+<p>
+</p>
+<h2><a name="records__"><code>records()</code></a></h2>
+<pre>
+ @records = $rs->records();
+ foreach $rec (@records) {
+ print $rec->render();
+ }</pre>
+<p>This utility method returns a list of all the records in the result
+set I$<rs>. Because Perl arrays are indexed from zero, the first
+record is <code>$records[0]</code>, the second is <code>$records[1]</code>, <em>etc.</em></p>
+<p>If not all the records associated with <em>$rs</em> have yet been
+transferred from the server, then they need to be transferred at this
+point. This means that the <code>records()</code> method may block, and so is
+not recommended for use in applications that interact with multiple
+servers simultaneously. It does also have the side-effect that
+subsequent invocations of the <code>record()</code> method will always
+immediately return either a legitimate record or a ``real error''
+rather than a ``not yet'' indicator.</p>
+<p>If an error occurs, an empty list is returned. Since this is also
+what's returned when the search had zero hits, well-behaved
+applications will consult <code>$rs-</code>size()> in these circumstances to
+determine which of these two conditions pertains. After an error has
+occurred, details may be obtained via the result set's <code>errcode()</code>
+and <code>addinfo()</code> methods.</p>
+<p>If a non-empty list is returned, then individual elements of that list
+may still be undefined, indicating that corresponding record could not
+be fetched. In order to get more information, it's necessary to
+attempt to fetch the record using the <code>record()</code> method, then consult
+the <code>errcode()</code> and <code>addinfo()</code> methods.</p>
+<p><strong>Unwarranted personal opinion</strong>: all in all, this method is a pleasant
+short-cut for trivial programs to use, but probably carries too many
+caveats to be used extensively in serious applications. You may want to
+take a look at <code>present()</code> and the <code>prefetch</code> option instead.</p>
+<p><strong>AS OF RELEASE 0.31, THIS METHOD IS NOW DEPRECATED.
+PLEASE USE record() INSTEAD.</strong></p>
+<p>
+</p>
+<h2><a name="delete__"><code>delete()</code></a></h2>
+<pre>
+ $ok = $rs->delete();
+ if (!$ok) {
+ print "can't delete: ", $rs->errmsg(), "\n";
+ }</pre>
+<p>Requests the server to delete the result set corresponding to <code>$rs</code>.
+Return non-zero on success, zero on failure.</p>
+<p>
+</p>
+<h2><a name="errcode____addinfo____errmsg__">errcode(), addinfo(), <code>errmsg()</code></a></h2>
+<pre>
+ if (!defined $rs->record($i)) {
+ print "error ", $rs->errcode(), " (", $rs->errmsg(), ")\n";
+ print "additional info: ", $rs->addinfo(), "\n";
+ }</pre>
+<p>When a result set's <code>record()</code> method returns an undefined value,
+indicating an error, it also sets into the result set the BIB-1 error
+code and additional information returned by the server. They can be
+retrieved via the <code>errcode()</code> and <code>addinfo()</code> methods.</p>
+<p>As a convenience, <code>$rs-</code>errmsg()> is equivalent to
+<code>Net::Z3950::errstr($rs-</code>errcode())>.</p>
+<p>
+</p>
+<h2><a name="option__"><code>option()</code></a></h2>
+<pre>
+ $value = $rs->option($type);
+ $value = $rs->option($type, $newval);</pre>
+<p>Returns <em>$rs</em>'s value of the standard option <em>$type</em>, as registered
+in <em>$rs</em> itself, in the connection across which it was created, in
+the manager which controls that connection, or in the global defaults.</p>
+<p>If <em>$newval</em> is specified, then it is set as the new value of that
+option in <em>$rs</em>, and the option's old value is returned.</p>
+<p>
+</p>
+<hr />
+<h1><a name="author">AUTHOR</a></h1>
+<p>Mike Taylor <<a href="mailto:mike at indexdata.com">mike at indexdata.com</a>></p>
+<p>First version Sunday 28th May 2000.</p>
+
+</body>
+
+</html>
Added: packages/libnet-z3950-perl/trunk/doc/html/Z3950/Tutorial.html
===================================================================
--- packages/libnet-z3950-perl/trunk/doc/html/Z3950/Tutorial.html 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/doc/html/Z3950/Tutorial.html 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,757 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Net::Z3950::Tutorial - tutorial for the Net::Z3950 module</title>
+<link rev="made" href="mailto:root at localhost" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#a_very_simple_client">A VERY SIMPLE CLIENT</a></li>
+ <li><a href="#how_it_works">HOW IT WORKS</a></li>
+ <li><a href="#more_complex_behaviour">MORE COMPLEX BEHAVIOUR</a></li>
+ <ul>
+
+ <li><a href="#searching">Searching</a></li>
+ <li><a href="#retrieval">Retrieval</a></li>
+ <li><a href="#scanning">Scanning</a></li>
+ </ul>
+
+ <li><a href="#what_to_do_with_your_records">WHAT TO DO WITH YOUR RECORDS</a></li>
+ <ul>
+
+ <li><a href="#marc_records">MARC RECORDS</a></li>
+ <li><a href="#grs1_records">GRS-1 RECORDS</a></li>
+ </ul>
+
+ <li><a href="#changing_session_parameters">CHANGING SESSION PARAMETERS</a></li>
+ <ul>
+
+ <li><a href="#make_or_find_a_manager">Make or Find a Manager</a></li>
+ <li><a href="#set_the_parameters">Set the Parameters</a></li>
+ </ul>
+
+ <li><a href="#option_inheritance">OPTION INHERITANCE</a></li>
+ <li><a href="#asynchronous_mode">ASYNCHRONOUS MODE</a></li>
+ <li><a href="#now_what">NOW WHAT?</a></li>
+ <li><a href="#author">AUTHOR</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Net::Z3950::Tutorial - tutorial for the Net::Z3950 module</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<p>Apparently, every POD document has to have a SYNOPSIS. So here's one.</p>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p><code>Net::Z3950</code> is a Perl module for writing Z39.50 clients. (If you
+want to write a Z39.50 server, you want the
+<code>Net::Z3950::SimpleServer</code> module.)</p>
+<p>Its goal is to hide all the messy details of the Z39.50 protocol - at
+least by default - while providing access to all of its glorious
+power. Sometimes, this involves revealing the messy details after
+all, but at least this is the programmer's choice. The result is that
+writing Z39.50 clients works the way it should according my favourite
+of the various Perl mottos: ``Simple things should be simple, and
+difficult things should be possible.''</p>
+<p>If you don't know what Z39.50 is, then the best place to find out is
+at
+<a href="http://lcweb.loc.gov/z3950/agency/">http://lcweb.loc.gov/z3950/agency/</a>
+the web site of the Z39.50 Maintenance Agency. Among its many other
+delights, this site contains a complete downloadable soft-copy of the
+standard itself. In briefest summary, Z39.50 is the international
+standard for distributed searching and retrieval.</p>
+<p>
+</p>
+<hr />
+<h1><a name="a_very_simple_client">A VERY SIMPLE CLIENT</a></h1>
+<p>The <code>Net::Z3950</code> distribution includes a couple of sample clients in
+the <code>samples</code> directory. The simplest of them, <code>trivial.pl</code> reads
+as follows:</p>
+<pre>
+ use Net::Z3950;
+ $conn = new Net::Z3950::Connection('indexdata.dk', 210,
+ databaseName => 'gils');
+ $rs = $conn->search('mineral');
+ print "found ", $rs->size(), " records:\n";
+ my $rec = $rs->record(1);
+ print $rec->render();</pre>
+<p>This complete program retrieves from the database called ``gils'' on
+the Z39.50 server on port 210 of <code>indexdata.dk</code> the first record
+matching the search ``mineral'', and renders it in human-readable
+form. Typical output would look like this:</p>
+<pre>
+ 6 fields:
+ (1,1) 1.2.840.10003.13.2
+ (1,14) "2"
+ (2,1) {
+ (1,19) "UTAH EARTHQUAKE EPICENTERS"
+ (3,Acronym) "UUCCSEIS"
+ }
+ (4,52) "UTAH GEOLOGICAL AND MINERAL SURVEY"
+ (4,1) "ESDD0006"
+ (1,16) "198903"</pre>
+<p>
+</p>
+<hr />
+<h1><a name="how_it_works">HOW IT WORKS</a></h1>
+<p>Let's pick the trivial client apart line by line (it won't take long!)</p>
+<pre>
+ use Net::Z3950;</pre>
+<p>This line simply tells Perl to pull in the <code>Net::Z3950</code> module - a
+prerequisite for using types like <code>Net::Z3950::Connection</code>.</p>
+<pre>
+ $conn = new Net::Z3950::Connection('indexdata.dk', 210,
+ databaseName => 'gils');</pre>
+<p>Creates a new connection to the Z39.50 server on port 210 of the host
+<code>indexdata.dk</code>, noting that searches on this connection will default
+to the database called ``gils''. A reference to the new connection is
+stored in <code>$conn</code>.</p>
+<pre>
+ $rs = $conn->search('mineral');</pre>
+<p>Performs a single-word search on the connection referenced by <code>$conn</code>
+(in the previously established default database, ``gils''.) In
+response, the server generates an <em>result set</em>, notionally containing
+all the matching records; a reference to the new connection is stored
+in <code>$rs</code>.</p>
+<pre>
+ print "found ", $rs->size(), " records:\n";</pre>
+<p>Prints the number of records in the new result set <code>$rs</code>.</p>
+<pre>
+ my $rec = $rs->record(1);</pre>
+<p>Fetches from the server the first record in the result set <code>$rs</code>,
+requesting the default record syntax (GRS-1) and the default element
+set (brief, ``b''); a reference to the newly retrieved record is
+stored in <code>$rec</code>.</p>
+<pre>
+ print $rec->render();</pre>
+<p>Prints a human-readable rendition of the record <code>$rec</code>. The exact
+format of the rendition is dependent on issues like the record syntax
+of the record that the server sent.</p>
+<p>
+</p>
+<hr />
+<h1><a name="more_complex_behaviour">MORE COMPLEX BEHAVIOUR</a></h1>
+<p>
+</p>
+<h2><a name="searching">Searching</a></h2>
+<p>Searches may be specified in one of several different syntaxes.
+The default
+syntax is so-called Prefix Query Notation, or PQN, a bespoke format
+invented by Index Data to map simply to the Z39.50 type-1 query
+structure. A second is the Common Command Language (CCL) an
+international standard query language often used in libraries.
+The third is the Common Query Language (CQL) the query language
+used by SRW and SRU.</p>
+<p>CCL queries may be interpreted on the client side and translated into
+a type-1 query which is forwarded to the server; or it may be sent
+``as is'' for the server to interpret as it may. CQL queries may only
+be passed ``as is''.</p>
+<p>The interpretation of the search string may be specified by passing an
+argument of <code>-prefix</code>, <code>-ccl</code>, <code>-ccl2rpn</code> or <code>-cql</code> to the <code>search()</code>
+method before the search string itself, as follows:</p>
+<p><strong>Prefix Queries</strong></p>
+<pre>
+ $rs = $conn->search(-prefix => '@or rock @attr 1=21 mineral');</pre>
+<p>Prefix Query Notation is fully described in section 8.1 (<strong>Query
+Syntax Parsers</strong>) of the Yaz toolkit documentation, <strong>YAZ User's Guide
+and Reference</strong>.</p>
+<p>Briefly, however, keywords begin with an <code>@</code>-sign, and all other
+words are interpreted as search terms. Keywords include the binary
+operators <code>@and</code> and <code>@or</code>, which join together the two operands
+that follow them, and <code>@attr</code>, which introduces a <em>type</em>=<em>value</em>
+expression specifying an attribute to be applied to the following
+term.</p>
+<p>So:</p>
+<ul>
+<li></li>
+<code>fruit</code> searches for the term ``fruit'',
+<p></p>
+<li></li>
+<code>@and fruit fish</code> searches for records containing both ``fruit'' and
+``fish'',
+<p></p>
+<li></li>
+<code>@or fish chicken</code> searches for records containing either ``fish'' or
+``chicken'' (or both),
+<p></p>
+<li></li>
+<code>@and fruit @or fish chicken</code> searches for records containing both
+``fruit'' and at least one of ``fish'' or ``chicken''.
+<p></p>
+<li></li>
+<code>@or rock @attr 1=21 mineral</code> searches for records either containing
+``rock'' or ``mineral'', but with the ``mineral'' search term carrying
+an attribute of type 1, with value 21 (typically interpreted to mean
+that the search term must occur in the ``subject'' field of the
+record.)
+<p></p></ul>
+<p><strong>CCL Queries</strong></p>
+<pre>
+ $rs = $conn->search(-ccl2rpn => 'rock or su=mineral');
+ $rs = $conn->search(-ccl => 'rock or su=mineral');</pre>
+<p>CCL is formally specified in the international standard ISO 8777
+(<strong>Commands for interactive text searching</strong>) and also described in
+section 8.1 (<strong>Query Syntax Parsers</strong>) of the Yaz toolkit
+documentation, <strong>YAZ User's Guide and Reference</strong>.</p>
+<p>Briefly, however, there is a set of well-known keywords including
+<code>and</code>, <code>or</code> and <code>not</code>. Words other than these are interpreted as
+search terms. Operating grouping (precedence) is specified by
+parentheses, and the semantics of a search term may be modified by
+prepending one or more comma-separated qualifiers qualifiers and an
+equals sign.</p>
+<p>So:</p>
+<ul>
+<li></li>
+<code>fruit</code> searches for the term ``fruit'',
+<p></p>
+<li></li>
+<code>fruit and fish</code> searches for records containing both ``fruit'' and
+``fish'',
+<p></p>
+<li></li>
+<code>fish or chicken</code> searches for records containing either ``fish'' or
+``chicken'' (or both),
+<p></p>
+<li></li>
+<code>fruit and (fish or chicken)</code> searches for records containing both
+``fruit'' and at least one of ``fish'' or ``chicken''.
+<p></p>
+<li></li>
+<code>rock or su=mineral</code> searches for records either containing
+``rock'' or ``mineral'', but with the ``mineral'' search term modified
+by the qualifier ``su'' (typically interpreted to mean that the search
+term must occur in the ``subject'' field of the record.)
+<p></p></ul>
+<p>For CCL searches sent directly to the server (query type <code>ccl</code>), the
+exact interpretation of the qualifiers is the server's
+responsibility. For searches compiled on the client side (query side
+<code>ccl2rpn</code>) the interpretation of the qualifiers in terms of type-1
+attributes is determined by the contents of a file called
+<em>### not yet implemented</em>.
+The format of this file is described in the Yaz documentation.</p>
+<p><strong>CQL Queries</strong></p>
+<pre>
+ $rs = $conn->search(-cql => 'au-(kernighan and ritchie)');</pre>
+<p>CQL syntax is very similar to that of CCL.</p>
+<p><strong>Setting Search Defaults</strong></p>
+<p>As an alternative to explicitly specifying the query type when
+invoking the <code>search()</code> method, you can change the connection's
+default query type using its <code>option()</code> method:</p>
+<pre>
+ $conn->option(querytype => 'prefix');
+ $conn->option(querytype => 'ccl');
+ $conn->option(querytype => 'ccl2rpn');</pre>
+<p>The connection's current default query type can be retrieved using
+<code>option()</code> with no ``value'' argument:</p>
+<pre>
+ $qt = $conn->option('querytype');</pre>
+<p>The <code>option()</code> method can be used to set and get numerous other
+defaults described in this document and elsewhere; this method exists
+not only on connections but also on managers (q.v.) and result sets.</p>
+<p>Another important option is <a href="#item_databasename"><code>databaseName</code></a>, whose value specifies
+which database is to be searched.</p>
+<p>
+</p>
+<h2><a name="retrieval">Retrieval</a></h2>
+<p>By default, records are requested from the server one at a time;
+this can be quite slow when retrieving several records. There are two
+ways of improving this. First, the <code>present()</code> method can be used to
+explicitly precharge the cache. Its parameters are a start record and
+record count. In the following example, the <code>present()</code> is optional and
+merely makes the code run faster:</p>
+<pre>
+ $rs->present(11, 5) or die ".....";
+ foreach my $i (11..15) {
+ my $rec = $rs->record($i);
+ ...
+ }</pre>
+<p>The second way is with the <code>prefetch</code> option. Setting this to a
+positive integer makes the <code>record()</code> method fetch the next N
+records and place them in the cache if the the current record
+isn't already there. So the following code would cause two bouts of
+network activity, each retrieving 10 records.</p>
+<pre>
+ $rs->option(prefetch => 10);
+ foreach my $i (1..20) {
+ my $rec = $rs->record($i);
+ ...
+ }</pre>
+<p>In asynchronous mode, <code>present()</code> and <code>prefetch</code> merely cause the
+records to be scheduled for retrieval.</p>
+<p><strong>Element Set</strong></p>
+<p>The default element set is ``b'' (brief). To change this, set the
+result set's <a href="#item_elementsetname"><code>elementSetName</code></a> option:</p>
+<pre>
+ $rs->option(elementSetName => "f");</pre>
+<p><strong>Record Syntax</strong></p>
+<p>The default record syntax preferred by the <code>Net::Z3950</code> module is
+GRS-1 (the One True Record syntax). If, however, you need to ask the
+server for a record using a different record syntax, then the way to
+do this is to set the <a href="#item_preferredrecordsyntax"><code>preferredRecordSyntax</code></a> option of the result
+set from which the record is to be fetched:</p>
+<pre>
+ $rs->option(preferredRecordSyntax => "SUTRS");</pre>
+<p>The record syntaxes which may be requested are listed in the
+<code>Net::Z3950::RecordSyntax</code> enumeration in the file <code>Net/Z3950.pm</code>;
+they include
+<code>Net::Z3950::RecordSyntax::GRS1</code>,
+<code>Net::Z3950::RecordSyntax::SUTRS</code>,
+<code>Net::Z3950::RecordSyntax::USMARC</code>,
+<code>Net::Z3950::RecordSyntax::TEXT_XML</code>,
+<code>Net::Z3950::RecordSyntax::APPLICATION_XML</code>
+and
+<code>Net::Z3950::RecordSyntax::TEXT_HTML</code></p>
+<p>(As always, <code>option()</code> may also be invoked with no ``value''
+parameter to return the current value of the option.)</p>
+<p>
+</p>
+<h2><a name="scanning">Scanning</a></h2>
+<p><strong>### Note to self - write this section!</strong></p>
+<p>
+</p>
+<hr />
+<h1><a name="what_to_do_with_your_records">WHAT TO DO WITH YOUR RECORDS</a></h1>
+<p>Once you've retrieved a record, what can you do with it?</p>
+<p>There are two broad approaches. One is just to display it to the
+user: this can always be done with the <code>render()</code> method, as used in
+the sample code above, whatever the record syntax of the record.</p>
+<p>The more sophisticated approach is to perform appropriate analysis and
+manipulation of the raw record according to the record syntax. The
+raw data is retrieved using the <code>rawdata()</code> method, and the record
+syntax can be determined using the universal <code>isa()</code> method:</p>
+<pre>
+ $raw = $rec->rawdata();
+ if ($rec->isa('Net::Z3950::Record::GRS1')) {
+ process_grs1_record($raw);
+ elsif ($rec->isa('Net::Z3950::Record::USMARC')) {
+ process_marc_record($raw);
+ } # etc.</pre>
+<p>
+</p>
+<h2><a name="marc_records">MARC RECORDS</a></h2>
+<p>For further manipulation of MARC records, we recommend the existing
+MARC module in Ed Summers's directory at CPAN,
+<a href="http://cpan.valueclick.com/authors/id/E/ES/ESUMMERS/">http://cpan.valueclick.com/authors/id/E/ES/ESUMMERS/</a></p>
+<p>
+</p>
+<h2><a name="grs1_records">GRS-1 RECORDS</a></h2>
+<p>The raw data of GRS-1 records in the <code>Net::Z3950</code> module closely
+follows the structure of physcial GRS-1 records - see Appendices REC.5
+(<strong>Generic Record Syntax 1</strong>), TAG (<strong>TagSet Definitions and Schemas</strong>)
+and RET (<strong>Z39.50 Retrieval</strong>) of the standard more details.</p>
+<p>The raw GRS-1 data is intended to be more or less self-describing, but
+here is a summary.</p>
+<ul>
+<li></li>
+The raw data is a reference to an array of elements, each representing
+one of the fields of the record.
+<p></p>
+<li></li>
+Each element is a <code>Net::Z3950::APDU::TaggedElement</code> object. These
+objects support the accessor methods <code>tagType()</code>, <code>tagValue()</code>,
+<code>tagOccurrence()</code> and <code>content()</code>; the first three of these return
+numeric values, or strings in the less common case of string
+tag-values.
+<p></p>
+<li></li>
+The <code>content()</code> of an element is an object of type
+<code>Net::Z3950::ElementData</code>. Its <code>which()</code> method returns a constant
+indicating the type of the content, which may be any of the following:
+<ul>
+<li></li>
+<code>Net::Z3950::ElementData::Numeric</code>
+indicates that the content is a number;
+access it via the
+<code>numeric()</code>
+method.
+<p></p>
+<li></li>
+<code>Net::Z3950::ElementData::String</code>
+indicates that the content is a string of characters;
+access it via the
+<code>string()</code>
+method.
+<p></p>
+<li></li>
+<code>Net::Z3950::ElementData::OID</code>
+indicates that the content is an OID, represented as a string with the
+components separated by periods (``<code>.</code>'');
+access it via the
+<code>oid()</code>
+method.
+<p></p>
+<li></li>
+<code>Net::Z3950::ElementData::Subtree</code>
+is
+a reference to another <code>Net::Z3950::Record::GRS1</code> object, enabling
+arbitrary recursive nesting;
+access it via the
+<code>subtree()</code>
+method.
+<p></p></ul>
+</ul>
+<p>In the future, we plan to take you away from all this by introducing a
+<code>Net::Z3950::Data</code> module which provides a DOM-like interface for
+walking hierarchically structured records independently of their
+record syntax. Keep watchin', kids!</p>
+<p>
+</p>
+<hr />
+<h1><a name="changing_session_parameters">CHANGING SESSION PARAMETERS</a></h1>
+<p>As with customising searching or retrieval behaviour, whole-session
+behaviour is customised by setting options. However, this needs to be
+done before the session is created, because the Z39.50 protocol
+doesn't provide a method for changing (for example) the preferred
+message size of an existing connection.</p>
+<p>In the <code>Net::Z3950</code> module, this is done by creating a <em>manager</em> - a
+controller for one or more connections. Then the manager's options
+can be set; then connections which are opened through the manager use
+the specified values for those options.</p>
+<p>As a matter of fact, <em>every</em> connection is made through a manager.
+If one is not specified in the connection constructor, then the
+``default manager'' is used; it's automatically created the first time
+it's needed, then re-used for any other connections that need it.</p>
+<p>
+</p>
+<h2><a name="make_or_find_a_manager">Make or Find a Manager</a></h2>
+<p>A new manager is created as follows:</p>
+<pre>
+ $mgr = new Net::Z3950::Manager();</pre>
+<p>Once the manager exists, a new connection can be made through it by
+specifying the manager reference as the first argument to the connection
+constructor:</p>
+<pre>
+ $conn = new Net::Z3950::Connection($mgr, 'indexdata.dk', 210);</pre>
+<p>Or equivalently,</p>
+<pre>
+ $conn = $mgr->connect('indexdata.dk', 210);</pre>
+<p>In order to retrieve the manager through which a connection was made,
+whether it was the implicit default manager or not, use the
+<code>manager()</code> method:</p>
+<pre>
+ $mgr = $conn->manager();</pre>
+<p>
+</p>
+<h2><a name="set_the_parameters">Set the Parameters</a></h2>
+<p>There are two ways to set parameters. One we have already seen: the
+<code>option()</code> method can be used to get and set option values for
+managers just as it can for connections and result sets:</p>
+<pre>
+ $pms = $mgr->option('preferredMessageSize');
+ $mgr->option(preferredMessageSize => $pms*2);</pre>
+<p>Alternatively, options may be passed to the manager constructor when
+the manager is first created:</p>
+<pre>
+ $mgr = new Net::Z3950::Manager(
+ preferredMessageSize => 100*1024,
+ maximumRecordSize => 10*1024*1024,
+ preferredRecordSyntax => "GRS-1");</pre>
+<p>This is <em>exactly</em> equivalent to creating a ``vanilla'' manager with
+<code>new Net::Z3950::Manager()</code>, then setting the three options with the
+<code>option()</code> method.</p>
+<p><strong>Message Size Parameters</strong></p>
+<p>The <a href="#item_preferredmessagesize"><code>preferredMessageSize</code></a> and <a href="#item_maximumrecordsize"><code>maximumRecordSize</code></a> parameters can be
+used to specify values of the corresponding parameters which are
+proposed to the server at initialisation time (although the server is
+not bound to honour them.) See sections 3.2.1.1.4
+(<strong>Preferred-message-size and Exceptional-message-size</strong>) and 3.3
+(<strong>Message/Record Size and Segmentation</strong>) of the Z39.50 standard
+itself for details.</p>
+<p>Both options default to one megabyte.</p>
+<p><strong>Implementation Identification</strong></p>
+<p>The <a href="#item_implementationid"><code>implementationId</code></a>, <a href="#item_implementationname"><code>implementationName</code></a> and
+<a href="#item_implementationversion"><code>implementationVersion</code></a> options can be used to control the
+corresponding parameters in initialisation request sent to the server
+to identify the client. The default values are listed below in the
+section <strong>OPTION INHERITANCE</strong>.</p>
+<p><strong>Authentication</strong></p>
+<p>The <a href="#item_user"><code>user</code></a>, <a href="#item_pass"><code>pass</code></a> and <a href="#item_group"><code>group</code></a> options can be specified for a
+manager so that they are passed as identification tokens at
+initialisation time to any connections opened through that manager.
+The three options are interpreted as follows:</p>
+<ul>
+<li></li>
+If <a href="#item_user"><code>user</code></a> is not specified, then authentication is omitted (which is
+more or less the same as ``anonymous'' authentication).
+<p></p>
+<li></li>
+If <a href="#item_user"><code>user</code></a> is specified but not <a href="#item_pass"><code>pass</code></a>, then the value of the
+<a href="#item_user"><code>user</code></a> option is passed as an ``open'' authentication token.
+<p></p>
+<li></li>
+If both <a href="#item_user"><code>user</code></a> and <a href="#item_pass"><code>pass</code></a> are specified, then their values are
+passed in an ``idPass'' authentication structure, together with the
+value of <a href="#item_group"><code>group</code></a> if is it specified.
+<p></p></ul>
+<p>By default, all three options are undefined, so no authentication is
+used.</p>
+<p><strong>Character set and language negotiation</strong></p>
+<p>The <a href="#item_charset"><code>charset</code></a> and <a href="#item_language"><code>language</code></a> options can be used to negotiate the
+character set and language to be used for connections opened through
+that manager. If these options are set, they are passed to the server
+in a character-negotition otherInfo package attached to the
+initialisation request.</p>
+<p>
+</p>
+<hr />
+<h1><a name="option_inheritance">OPTION INHERITANCE</a></h1>
+<p>The values of options are inherited from managers to connections,
+result sets and finally to records.</p>
+<p>This means that when a record is asked for an option value (whether by
+an application invoking its <code>option()</code> method, or by code inside the
+module that needs to know how to behave), that value is looked for
+first in the record's own table of options; then, if it's not
+specified there, in the options of the result set from which the
+record was retrieved; then if it's not specified there, in those of
+the connection across which the result set was found; and finally, if
+not specified there either, in the options for the manager through
+which the connection was created.</p>
+<p>Similarly, option values requested from a result set are looked up (if
+not specified in the result set itself) in the connection, then the
+manager; and values requested from a connection fall back to its
+manager.</p>
+<p>This is why it made sense in an earlier example (see the section <strong>Set
+the Parameters</strong>) to specify a value for the <a href="#item_preferredrecordsyntax"><code>preferredRecordSyntax</code></a>
+option when creating a manager: the result of this is that, unless
+overridden, it will be the preferred record syntax when any record is
+retrieved from any result set retrieved from any connection created
+through that manager. In effect, it establishes a global default.
+Alternatively, one might specify different defaults on two different
+connections.</p>
+<p>In all cases, if the manager doesn't have a value for the requested
+option, then a hard-wired default is used. The defaults are as
+follows. (Please excuse the execrable formatting - that's what
+<code>pod2html</code> does, and there's no sensible way around it.)</p>
+<dl>
+<dt><strong><a name="item_die_handler"><code>die_handler</code></a></strong><br />
+</dt>
+<dd>
+<code>undef</code>
+A function to invoke if <code>die()</code> is called within the main event loop.
+</dd>
+<p></p>
+<dt><strong><a name="item_timeout"><code>timeout</code></a></strong><br />
+</dt>
+<dd>
+<code>undef</code>
+The maximum number of seconds a manager will wait when its <code>wait()</code>
+method is called. If the timeout elapses, <code>wait()</code> returns an
+undefined value. <strong>Can not be set on a per-connection basis.</strong>
+</dd>
+<p></p>
+<dt><strong><a name="item_async"><code>async</code></a></strong><br />
+</dt>
+<dd>
+<code>0</code>
+(Determines whether a given connection is in asynchronous mode.)
+</dd>
+<p></p>
+<dt><strong><a name="item_preferredmessagesize"><code>preferredMessageSize</code></a></strong><br />
+</dt>
+<dd>
+<code>1024*1024</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_maximumrecordsize"><code>maximumRecordSize</code></a></strong><br />
+</dt>
+<dd>
+<code>1024*1024</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_user"><code>user</code></a></strong><br />
+</dt>
+<dd>
+<code>undef</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_pass"><code>pass</code></a></strong><br />
+</dt>
+<dd>
+<code>undef</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_group"><code>group</code></a></strong><br />
+</dt>
+<dd>
+<code>undef</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_implementationid"><code>implementationId</code></a></strong><br />
+</dt>
+<dd>
+<code>'Mike Taylor (id=169)'</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_implementationname"><code>implementationName</code></a></strong><br />
+</dt>
+<dd>
+<code>'Net::Z3950.pm (Perl)'</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_implementationversion"><code>implementationVersion</code></a></strong><br />
+</dt>
+<dd>
+<code>$Net::Z3950::VERSION</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_charset"><code>charset</code></a></strong><br />
+</dt>
+<dd>
+<code>undef</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_language"><code>language</code></a></strong><br />
+</dt>
+<dd>
+<code>undef</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_querytype"><code>querytype</code></a></strong><br />
+</dt>
+<dd>
+<code>'prefix'</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_databasename"><code>databaseName</code></a></strong><br />
+</dt>
+<dd>
+<code>'Default'</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_smallsetupperbound"><code>smallSetUpperBound</code></a></strong><br />
+</dt>
+<dd>
+<code>0</code>
+(This and the next four options provide flexible control for run-time
+details such as what record syntax to use when returning records. See
+sections
+3.2.2.1.4 (<strong>Small-set-element-set-names and
+Medium-set-element-set-names</strong>)
+and
+3.2.2.1.6 (<strong>Small-set-upper-bound, Large-set-lower-bound, and
+Medium-set-present-number</strong>)
+of the Z39.50 standard itself for details.)
+</dd>
+<p></p>
+<dt><strong><a name="item_largesetlowerbound"><code>largeSetLowerBound</code></a></strong><br />
+</dt>
+<dd>
+<code>1</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_mediumsetpresentnumber"><code>mediumSetPresentNumber</code></a></strong><br />
+</dt>
+<dd>
+<code>0</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_smallsetelementsetname"><code>smallSetElementSetName</code></a></strong><br />
+</dt>
+<dd>
+<code>'f'</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_mediumsetelementsetname"><code>mediumSetElementSetName</code></a></strong><br />
+</dt>
+<dd>
+<code>'b'</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_preferredrecordsyntax"><code>preferredRecordSyntax</code></a></strong><br />
+</dt>
+<dd>
+<code>'GRS-1'</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_responseposition"><code>responsePosition</code></a></strong><br />
+</dt>
+<dd>
+<code>1</code>
+(Indicates the one-based position of the start term in the set of
+terms returned from a scan.)
+</dd>
+<p></p>
+<dt><strong><a name="item_stepsize"><code>stepSize</code></a></strong><br />
+</dt>
+<dd>
+<code>0</code>
+(Indicates the number of terms between each of the terms returned from
+a scan.)
+</dd>
+<p></p>
+<dt><strong><a name="item_numberofentries"><code>numberOfEntries</code></a></strong><br />
+</dt>
+<dd>
+<code>20</code>
+(Indicates the number of terms to return from a scan.)
+</dd>
+<p></p>
+<dt><strong><a name="item_elementsetname"><code>elementSetName</code></a></strong><br />
+</dt>
+<dd>
+<code>'b'</code>
+</dd>
+<p></p>
+<dt><strong><a name="item_namedresultsets"><code>namedResultSets</code></a></strong><br />
+</dt>
+<dd>
+<code>1</code> indicating boolean true. This option tells the client to use a
+new result set name for each new result set generated, so that old
+<code>ResultSet</code> objects remain valid. For the benefit of old, broken
+servers, this option may be set to 0, indicating that same result-set
+name, <code>default</code>, should be used for each search, so that each search
+invalidates all existing <code>ResultSet</code>s.
+</dd>
+<p></p></dl>
+<p>Any other option's value is undefined.</p>
+<p>
+</p>
+<hr />
+<h1><a name="asynchronous_mode">ASYNCHRONOUS MODE</a></h1>
+<p>I don't propose to discuss this at the moment, since I think it's more
+important to get the Tutorial out there with the synchronous stuff in
+place than to write the asynchronous stuff. I'll do it soon, honest.
+In the mean time, let me be clear: the asynchronous code itself is
+done and works (the synchronous interface is merely a thin layer on
+top of it) - it's only the <em>documentation</em> that's not yet here.</p>
+<p><strong>### Note to self - write this section!</strong></p>
+<p>
+</p>
+<hr />
+<h1><a name="now_what">NOW WHAT?</a></h1>
+<p>This tutorial is only an overview of what can be done with the
+<code>Net::Z3950</code> module. If you need more information that it provides,
+then you need to read the more technical documentation on the
+individual classes that make up the module -
+<code>Net::Z3950</code> itself,
+<code>Net::Z3950::Manager</code>,
+<code>Net::Z3950::Connection</code>,
+<code>Net::Z3950::ResultSet</code> and
+<code>Net::Z3950::Record</code>.</p>
+<p>
+</p>
+<hr />
+<h1><a name="author">AUTHOR</a></h1>
+<p>Mike Taylor <<a href="mailto:mike at indexdata.com">mike at indexdata.com</a>></p>
+<p>First version Sunday 28th January 2001.</p>
+
+</body>
+
+</html>
Added: packages/libnet-z3950-perl/trunk/doc/html/Z3950/style.css
===================================================================
--- packages/libnet-z3950-perl/trunk/doc/html/Z3950/style.css 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/doc/html/Z3950/style.css 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,9 @@
+/*
+ * style.css -- HTML style-sheet for Net::Z3950 documentation
+ * $Header: /home/cvsroot/NetZ3950/doc/style.css,v 1.2 2001/10/19 15:40:25 mike Exp $
+ */
+body { color: #000040; background: white }
+h1 { color: #ffffa0; background: #a00000; margin-top: 20px;
+ padding: 5px 10px; border: 1px transparent }
+h2,h3,h4,h5,h6 { color: #600000 }
+.warning { color: #ff0000; background: #ffff80 }
Added: packages/libnet-z3950-perl/trunk/doc/html/style.css
===================================================================
--- packages/libnet-z3950-perl/trunk/doc/html/style.css 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/doc/html/style.css 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,9 @@
+/*
+ * style.css -- HTML style-sheet for Net::Z3950 documentation
+ * $Header: /home/cvsroot/NetZ3950/doc/style.css,v 1.2 2001/10/19 15:40:25 mike Exp $
+ */
+body { color: #000040; background: white }
+h1 { color: #ffffa0; background: #a00000; margin-top: 20px;
+ padding: 5px 10px; border: 1px transparent }
+h2,h3,h4,h5,h6 { color: #600000 }
+.warning { color: #ff0000; background: #ffff80 }
Property changes on: packages/libnet-z3950-perl/trunk/doc/htmlify
___________________________________________________________________
Name: svn:executable
-
+ *
Added: packages/libnet-z3950-perl/trunk/doc/pod2htmd.tmp
===================================================================
--- packages/libnet-z3950-perl/trunk/doc/pod2htmd.tmp 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/doc/pod2htmd.tmp 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,2 @@
+
+.
Added: packages/libnet-z3950-perl/trunk/doc/pod2htmi.tmp
===================================================================
--- packages/libnet-z3950-perl/trunk/doc/pod2htmi.tmp 2006-02-25 20:49:01 UTC (rev 2207)
+++ packages/libnet-z3950-perl/trunk/doc/pod2htmi.tmp 2006-02-25 20:49:08 UTC (rev 2208)
@@ -0,0 +1,2 @@
+
+.
Property changes on: packages/libnet-z3950-perl/trunk/samples/fetch1.pl
___________________________________________________________________
Name: svn:executable
-
+ *
Property changes on: packages/libnet-z3950-perl/trunk/samples/multiplex.pl
___________________________________________________________________
Name: svn:executable
-
+ *
Property changes on: packages/libnet-z3950-perl/trunk/samples/simple.pl
___________________________________________________________________
Name: svn:executable
-
+ *
More information about the Pkg-perl-cvs-commits
mailing list