Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
ZOOM(3)		      User Contributed Perl Documentation	       ZOOM(3)

       ZOOM - Perl extension implementing the ZOOM API for Information

	use ZOOM;
	eval {
	    $conn = new	ZOOM::Connection($host,	$port,
					 databaseName => "mydb");
	    $conn->option(preferredRecordSyntax	=> "usmarc");
	    $rs	= $conn->search_pqf('@attr 1=4 dinosaur');
	    $n = $rs->size();
	    print $rs->record(0)->render();
	if ($@)	{
	    print "Error ", $@->code(),	": ", $@->message(), "\n";

       This module provides a nice, Perlish implementation of the ZOOM
       Abstract	API described and documented at

       the ZOOM	module is implemented as a set of thin classes on top of the
       non-OO functions	provided by this distribution's	"Net::Z3950::ZOOM"
       module, which in	turn is	a thin layer on	top of the ZOOM-C code
       supplied	as part	of Index Data's	YAZ Toolkit.  Because ZOOM-C is	also
       the underlying code that	implements ZOOM	bindings in C++, Visual	Basic,
       Scheme, Ruby, .NET (including C#) and other languages, this Perl	module
       works compatibly	with those other implementations.  (Of course, the
       point of	a public API such as ZOOM is that all implementations should
       be compatible anyway; but knowing that the same code is running is

       The ZOOM	module provides	two enumerations ("ZOOM::Error"	and
       "ZOOM::Event"), three utility functions "diag_str()", "event_str()" and
       "event()" in the	"ZOOM" package itself, and eight classes:
       "ZOOM::Exception", "ZOOM::Options", "ZOOM::Connection", "ZOOM::Query",
       "ZOOM::ResultSet", "ZOOM::Record", "ZOOM::ScanSet" and "ZOOM::Package".
       Of these, the Query class is abstract, and has four concrete
       subclasses: "ZOOM::Query::CQL", "ZOOM::Query::PQF",
       "ZOOM::Query::CQL2RPN" and "ZOOM::Query::CCL2RPN".  Finally, it also
       provides	a "ZOOM::Query::Log" module which supplies a useful general-
       purpose logging facility.  Many useful ZOOM applications	can be built
       using only the Connection, ResultSet, Record and	Exception classes, as
       in the example code-snippet above.

       A typical application will begin	by creating an Connection object, then
       using that to execute searches that yield ResultSet objects, then
       fetching	records	from the result-sets to	yield Record objects.  If an
       error occurs, an	Exception object is thrown and can be dealt with.

       More sophisticated applications might also browse the server's indexes
       to create a ScanSet, from which indexed terms may be retrieved; others
       might send ``Extended Services''	Packages to the	server,	to achieve
       non-standard tasks such as database creation and	record update.
       Searching using a query syntax other than PQF can be done using an
       query object of one of the Query	subclasses.  Finally, sets of options
       may be manipulated independently	of the objects they are	associated
       with using an Options object.

       In general, method calls	throw an exception if anything goes wrong, so
       you don't need to test for success after	each call.  See	the section
       below on	the Exception class for	details.

	$msg = ZOOM::diag_str(ZOOM::Error::INVALID_QUERY);

       Returns a human-readable	English-language string	corresponding to the
       error code that is its own parameter.  This works for any error-code
       returned	from "ZOOM::Exception::code()",	"ZOOM::Connection::error_x()"
       or "ZOOM::Connection::errcode()", irrespective of whether it is a
       member of the "ZOOM::Error" enumeration or drawn	from the BIB-1
       diagnostic set.

	$msg = ZOOM::diag_srw_str(18);

       Returns a human-readable	English-language string	corresponding to the
       specified SRW error code.

	$msg = ZOOM::event_str(ZOOM::Event::RECV_APDU);

       Returns a human-readable	English-language string	corresponding to the
       event code that is its own parameter.  This works for any value of the
       "ZOOM::Event" enumeration.

	$connsRef = [ $conn1, $conn2, $conn3 ];
	$which = ZOOM::event($connsRef);
	$ev = $connsRef->[$which-1]->last_event()
	    if ($which != 0);

       Used only in complex asynchronous applications, this function takes a
       reference to a list of Connection objects, waits	until an event occurs
       on any one of them, and returns an integer indicating which of the
       connections it occurred on.  The	return value is	a 1-based index	into
       the list; 0 is returned if no event occurs within the longest timeout
       specified by the	"timeout" options of all the connections.

       See the section below on	asynchronous applications.

       The eight ZOOM classes are described here in ``sensible order'':	first,
       the four	commonly used classes, in the he order that they will tend to
       be used in most programs	(Connection, ResultSet,	Record,	Exception);
       then the	four more esoteric classes in descending order of how often
       they are	needed.

       With the	exception of the Options class,	which is an extension to the
       ZOOM model, the introduction to each class includes a link to the
       relevant	section	of the ZOOM Abstract API.

	$conn =	new ZOOM::Connection("");
	print("server is '", $conn->option("serverImplementationName"),	"'\n");
	$conn->option(preferredRecordSyntax => "usmarc");
	$rs = $conn->search_pqf('@attr 1=4 mineral');
	$ss = $conn->scan('@attr 1=1003	a');
	if ($conn->errcode() !=	0) {
	   die("somthing went wrong: " . $conn->errmsg())

       This class represents a connection to an	information retrieval server,
       using an	IR protocol such as ANSI/NISO Z39.50, SRW (the Search/Retrieve
       Webservice), SRU	(the Search/Retrieve URL) or OpenSearch.  Not all of
       these protocols require a low-level connection to be maintained,	but
       the Connection object nevertheless provides a location for the
       necessary cache of configuration	and state information, as well as a
       uniform API to the connection-oriented facilities (searching, index
       browsing, etc.),	provided by these protocols.

       See the description of the "Connection" class in	the ZOOM Abstract API



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

       Creates a new Connection	object,	and immediately	connects it to the
       specified server.  If you want to make a	new Connection object but
       delay forging the connection, use the "create()"	and "connect()"
       methods instead.

       This constructor	can be called with two arguments or a single argument.
       In the former case, the arguments are the name and port number of the
       Z39.50 server to	connect	to; in the latter case,	the single argument is
       a YAZ service-specifier string of the form

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

       The server-name string is of the	form:

       o   [scheme:]host[:port][/databaseName]

       In which	the host and port parts	are as in the two-argument form, the
       databaseName if provided	specifies the name of the database to be used
       in subsequent searches on this connection, and the optional scheme
       (default	"tcp") indicates what protocol should be used.	At present,
       the following schemes are supported:

       tcp Z39.50 connection.

       ssl Z39.50 connection encrypted using SSL (Secure Sockets Layer).  Not
	   many	servers	support	this, but Index	Data's Zebra is	one that does.

	   Z39.50 connection on	a Unix-domain (local) socket, in which case
	   the hostname	portion	of the string is instead used as a filename in
	   the local filesystem.

	   SRU connection over HTTP.

       If the "http" scheme is used, the particular SRU	flavour	to be used may
       be specified by the "sru" option, which takes the following values:

	   SRU over SOAP (i.e. what used to be called SRW).  This is the

       get "SRU	Classic" (i.e. SRU over	HTTP GET).

	   SRU over HTTP POST.

       If an error occurs, an exception	is thrown.  This may indicate a
       networking problem (e.g.	the host is not	found or unreachable), or a
       protocol-level problem (e.g. a Z39.50 server rejected the Init

       create()	/ connect()

	$options = new ZOOM::Options();
	$options->option(implementationName => "my client");
	$options->option(implementationId => 12345);
	$conn =	create ZOOM::Connection($options)
	# or
	$conn =	create ZOOM::Connection(implementationName => "my client",
					implementationId => 12345);

	$conn->connect($host, 0);

       The usual Connection constructor, "new()" brings	a new object into
       existence and forges the	connection to the server all in	one operation,
       which is	often what you want.  For applications that need more control,
       however,	these two methods separate the two steps, allowing additional
       steps in	between	such as	the setting of options.

       "create()" creates and returns a	new Connection object, which is	not
       connected to any	server.	 It may	be passed an options block, of type
       "ZOOM::Options" (see below), into which options may be set before or
       after the creation of the Connection.  Alternatively and	equivalently,
       "create()" may be passed	a list of key-value option pairs directly.
       The connection to the server may	then be	forged by the "connect()"
       method, which accepts hostname and port arguments like those of the
       "new()" constructor.

       error_x() / errcode() / errmsg()	/ addinfo() / diagset()

	($errcode, $errmsg, $addinfo, $diagset)	= $conn->error_x();
	$errcode = $conn->errcode();
	$errmsg	= $conn->errmsg();
	$addinfo = $conn->addinfo();
	$diagset = $conn->diagset();

       These methods may be used to obtain information about the last error to
       have occurred on	a connection - although	typically they will not	been
       used, as	the same information is	available through the
       "ZOOM::Exception" that is thrown	when the error occurs.	The
       "errcode()", "errmsg()",	"addinfo()" and	"diagset()" methods each
       return one element of the diagnostic, and "error_x()" returns all four
       at once.

       See the "ZOOM::Exception" for the interpretation	of these elements.


	die $conn->exception();

       "exception()" returns the same information as "error_x()" in the	form
       of a "ZOOM::Exception" object which may be thrown or rendered.  If no
       error occurred on the connection, then "exception()" returns an
       undefined value.



       Checks whether an error is pending on the connection, and throw a
       "ZOOM::Exception" object	if so.	Since errors are thrown	as they	occur
       for synchronous connections, there is no	need ever to call this except
       in asynchronous applications.

       option()	/ option_binary()

	print("server is '", $conn->option("serverImplementationName"),	"'\n");
	$conn->option(preferredRecordSyntax => "usmarc");
	$conn->option_binary(iconBlob => "foo\0bar");
	die if length($conn->option_binary("iconBlob") != 7);

       Objects of the Connection, ResultSet, ScanSet and Package classes carry
       with them a set of named	options	which affect their behaviour in
       certain ways.  See the ZOOM-C options documentation for details:

       Connection options are listed at

       These options are set and fetched using the "option()" method, which
       may be called with either one or	two arguments.	In the two-argument
       form, the option	named by the first argument is set to the value	of the
       second argument,	and its	old value is returned.	In the one-argument
       form, the value of the specified	option is returned.

       For historical reasons, option values are not binary-clean, so that a
       value containing	a NUL byte will	be returned in truncated form.	The
       "option_binary()" method	behaves	identically to "option()" except that
       it is binary-clean, so that values containing NUL bytes are set and
       returned	correctly.

       search()	/ search_pqf()

	$rs = $conn->search(new	ZOOM::Query::CQL('title=dinosaur'));
	# The next two lines are equivalent
	$rs = $conn->search(new	ZOOM::Query::PQF('@attr	1=4 dinosaur'));
	$rs = $conn->search_pqf('@attr 1=4 dinosaur');

       The principal purpose of	a search-and-retrieve protocol is searching
       (and, er, retrieval), so	the principal method used on a Connection
       object is "search()".  It accepts a single argument, a "ZOOM::Query"
       object (or, more	precisely, an object of	a subclass of this class); and
       it creates and returns a	new ResultSet object representing the set of
       records resulting from the search.

       Since queries using PQF (Prefix Query Format) are so common, we make
       them a special case by providing	a "search_pqf()" method.  This is
       identical to "search()" except that it accepts a	string containing the
       query rather than an object, thereby obviating the need to create a
       "ZOOM::Query::PQF" object.  See the documentation of that class for
       information about PQF.

       scan() /	scan_pqf()

	$rs = $conn->scan(new ZOOM::Query::CQL('title=dinosaur'));
	# The next two lines are equivalent
	$rs = $conn->scan(new ZOOM::Query::PQF('@attr 1=4 dinosaur'));
	$rs = $conn->scan_pqf('@attr 1=4 dinosaur');

       Many Z39.50 servers allow you to	browse their indexes to	find terms to
       search for.  This is done using the "scan" method, which	creates	and
       returns a new ScanSet object representing the set of terms resulting
       from the	scan.

       "scan()"	takes a	single argument, but it	has to work hard: it specifies
       both what index to scan for terms, and where in the index to start
       scanning.  What's more, the specification of what index to scan
       includes	multiple facets, such as what database fields it's an index of
       (author,	subject, title,	etc.) and whether to scan for whole fields or
       single words (e.g. the title ``The Empire Strikes Back'', or the	four
       words ``Back'', ``Empire'', ``Strikes'' and ``The'', interleaved	with
       words from other	titles in the same index.

       All of this is done by using a Query object representing	a query	of a
       single term as the "scan()" argument.  The attributes associated	with
       the term	indicate which index is	to be used, and	the term itself
       indicates the point in the index	at which to start the scan.  For
       example,	if the argument	is the query "@attr 1=4	fish", then

       @attr 1=4
	   This	is the BIB-1 attribute with type 1 (meaning access-point,
	   which specifies an index), and type 4 (which	means ``title'').  So
	   the scan is in the title index.

	   Start the scan from the lexicographically earliest term that	is
	   equal to or falls after ``fish''.

       The argument "@attr 1=4 @attr 6=3 fish" would behave similarly; but the
       BIB-1 attribute 6=3 mean	completeness=``complete	field'', so the	scan
       would be	for complete titles rather than	for words occurring in titles.

       This takes a bit	of getting used	to.

       The behaviour is	"scan()" is affected by	the following options, which
       may be set on the Connection through which the scan is done:

       number [default:	10]
	   Indicates how many terms should be returned in the ScanSet.	The
	   number actually returned may	be less, if the	start-point is near
	   the end of the index, but will not be greater.

       position	[default: 1]
	   A 1-based index specifying where in the returned list of terms the
	   seed-term should appear.  By	default	it should be the first term
	   returned, but "position" may	be set,	for example, to	zero
	   (requesting the next	terms after the	seed-term), or to the same
	   value as "number" (requesting the index terms before	the seed

       stepSize	[default: 0]
	   An integer indicating how many indexed terms	are to be skipped
	   between each	one returned in	the ScanSet.  By default, no terms are
	   skipped, but	overriding this	can be useful to get a high-level
	   overview of the index.

	   Since scans using PQF (Prefix Query Format) are so common, we make
	   them	a special case by providing a "scan_pqf()" method.  This is
	   identical to	"scan()" except	that it	accepts	a string containing
	   the query rather than an object, thereby obviating the need to
	   create a "ZOOM::Query::PQF" object.


	$p = $conn->package();
	$o = new ZOOM::Options();
	$o->option(databaseName	=> "newdb");
	$p = $conn->package($o);

       Creates and returns a new "ZOOM::Package", to be	used in	invoking an
       Extended	Service.  An options block may optionally be passed in.	 See
       the "ZOOM::Package" documentation.


	if ($conn->last_event()	== ZOOM::Event::CONNECT) {
	    print "Connected!\n";

       Returns a "ZOOM::Event" enumerated value	indicating the type of the
       last event that occurred	on the connection.  This is used only in
       complex asynchronous applications - see the sections below on the
       "ZOOM::Event" enumeration and asynchronous applications.



       Destroys	a Connection object, tearing down any low-level	connection
       associated with it and freeing its resources.  It is an error to	reuse
       a Connection that has been "destroy()"ed.

	$rs = $conn->search_pqf('@attr 1=4 mineral');
	$n = $rs->size();
	for $i (1 .. $n) {
	    $rec = $rs->record($i-1);
	    print $rec->render();

       A ResultSet object represents the set of	zero or	more records resulting
       from a search, and is the means whereby these records can be retrieved.
       A ResultSet object may maintain client side cache or some, less,	none,
       all or more of the server's records: in general,	this is	supposed to an
       implementaton detail of no interest to a	typical	application, although
       more sophisticated applications do have facilities for messing with the
       cache.  Most applications will only need	the "size()", "record()" and
       "sort()"	methods.

       There is	no "new()" method nor any other	explicit constructor.  The
       only way	to create a new	ResultSet is by	using "search()" (or
       "search_pqf()") on a Connection.

       See the description of the "Result Set" class in	the ZOOM Abstract API



	$rs->option(elementSetName => "f");

       Allows options to be set	into, and read from, a ResultSet, just like
       the Connection class's "option()" method.  There	is no
       "option_binary()" method	for ResultSet objects.

       ResultSet options are listed at


	print "Found ",	$rs->size(), " records\n";

       Returns the number of records in	the result set.

       record()	/ record_immediate()

	$rec = $rs->record(0);
	$rec2 =	$rs->record_immediate(0);
	$rec3 =	$rs->record_immediate(1)
	    or print "second record wasn't in cache\n";

       The "record()" method returns a "ZOOM::Record" object representing a
       record from result-set, whose position is indicated by the argument
       passed in.  This	is a zero-based	index, so that legitimate values range
       from zero to "$rs->size()-1".

       The "record_immediate()"	API is identical, but it never invokes a
       network operation, merely returning the record from the ResultSet's
       cache if	it's already there, or an undefined value otherwise.  So if
       you use this method, you	must always check the return value.


	$rs->records(0,	10, 0);
	for $i (0..10) {
	    print $rs->record_immediate($i)->render();

	@nextseven = $rs->records(10, 7, 1);

       The "record_immediate()"	method only fetches records from the cache,
       whereas "record()" fetches them from the	server if they have not
       already been cached; but	the ZOOM module	has to guess what the most
       efficient strategy for this is.	It might fetch each record, alone when
       asked for: that's optimal in an application that's only interested in
       the top hit from	each search, but pessimal for one that wants to
       display a whole list of results.	 Conversely, the software's strategy
       might be	always to ask for blocks of a twenty records: that's great for
       assembling long lists of	things,	but wasteful when only one record is
       wanted.	The problem is that the	ZOOM module can't tell,	when you call
       "$rs->record()",	what your intention is.

       But you can tell	it.  The "records()" method fetches a sequence of
       records,	all in one go.	It takes three arguments: the first is the
       zero-based index	of the first record in the sequence, the second	is the
       number of records to fetch, and the third is a boolean indication of
       whether or not to return	the retrieved records as well as adding	them
       to the cache.  (You can always pass 1 for this if you like, and Perl
       will discard the	unused return value, but there is a small efficiency
       gain to be had by passing 0.)

       Once the	records	have been retrieved from the server (i.e. "records()"
       has completed without throwing an exception), they can be fetched much
       more efficiently	using "record()" - or "record_immediate()", which is
       then guaranteed to succeed.



       Resets the ResultSet's record cache, so that subsequent invocations of
       "record_immediate()" will fail.	I struggle to imagine a	real scenario
       where you'd want	to do this.


	if ($rs->sort("yaz", "1=4 >i 1=21 >s") < 0) {
	    die	"sort failed";

       Sorts the ResultSet in place (discarding	any cached records, as they
       will in general be sorted into a	different position).  There are	two
       arguments: the first is a string	indicating the type of the sort-
       specification, and the second is	the specification itself.

       The "sort()" method returns 0 on	success, or -1 if the sort-
       specification is	invalid.

       At present, the only supported sort-specification type is "yaz".	 Such
       a specification consists	of a space-separated sequence of keys, each of
       which itself consists of	two space-separated words (so that the total
       number of words in the sort-specification is even).  The	two words
       making up each key are a	field and a set	of flags.  The field can take
       one of two forms: if it contains	an "=" sign, then it is	a BIB-1
       type=value pair specifying which	field to sort (e.g. "1=4" for a	title
       sort); otherwise	it is sent for the server to interpret as best it can.
       The word	of flags is made up from one or	more of	the following: "s" for
       case sensitive, "i" for case insensitive; "<" for ascending order and
       ">" for descending order.

       For example, the	sort-specification in the code-fragment	above will
       sort the	records	in $rs case-insensitively in descending	order of
       title, with records having equivalent titles sorted case-sensitively in
       ascending order of subject.  (The BIB-1 access points 4 and 21
       represent title and subject respectively.)



       Destroys	a ResultSet object, freeing its	resources.  It is an error to
       reuse a ResultSet that has been "destroy()"ed.

	$rec = $rs->record($i);
	print $rec->render();
	$raw = $rec->raw();
	$marc =	new_from_usmarc	MARC::Record($raw);
	print "Record title is:	", $marc->title(), "\n";

       A Record	object represents a record that	has been retrived from the

       There is	no "new()" method nor any other	explicit constructor.  The
       only way	to create a new	Record is by using "record()" (or
       "record_immediate()", or	"records()") on	a ResultSet.

       In general, records are ``owned'' by their result-sets that they	were
       retrieved from, so they do not have to be explicitly memory-managed:
       they are	deallocated (and therefore can no longer be used) when the
       result-set is destroyed.

       See the description of the "Record" class in the	ZOOM Abstract API at


       error() / exception()

	if ($rec->error()) {
	    my($code, $msg, $addinfo, $dset) = $rec->error();
	    print "error $code,	$msg ($addinfo)	from $dset set\n";
	    die	$rec->exception();

       These functions test for	surrogate diagnostics associated with a
       record: that is,	errors pertaining to a particular record rather	than
       to the fetch-some-records operation as a	whole.	(The latter are	known
       in Z39.50 as non-surrogate diagnostics, and are reported	as exceptions
       thrown by searches.)  If	a particular record can't be obtained -	for
       example,	because	it is not available in the requested record syntax -
       then the	record object obtained from the	result-set, when interrogated
       with these functions, will report the error.

       "error()" returns the error-code, a human-readable message, additional
       information and the name	of the diagnostic set that the error is	from.
       When called in a	scalar context,	it just	returns	the error-code.	 Since
       error 0 means "no error", it can	be used	as a boolean has-there-been-
       an-error	indicator.

       "exception()" returns the same information in the form of a
       "ZOOM::Exception" object	which may be thrown or rendered.  If no	error
       occurred	on the record, then "exception()" returns an undefined value.


	print $rec->render();
	print $rec->render("charset=latin1,utf8");

       Returns a human-readable	representation of the record.  Beyond that, no
       promises	are made: careful programs should not make assumptions about
       the format of the returned string.

       If the optional argument	is provided, then it is	interpreted as in the
       "get()" method (q.v.)

       This method is useful mostly for	debugging.


	use MARC::Record;
	$raw = $rec->raw();
	$marc =	new_from_usmarc	MARC::Record($raw);
	$trans = $rec->render("charset=latin1,utf8");

       Returns an opaque blob of data that is the raw form of the record.
       Exactly what this is, and what you can do with it, varies depending on
       the record-syntax.  For example,	XML records will be returned as, well,
       XML; MARC records will be returned as ISO 2709-encoded blocks that can
       be decoded by software such as the fine "Marc::Record" module; GRS-1
       record will be ... gosh,	what an	interesting question.  But no-one uses
       GRS-1 any more, do they?

       If the optional argument	is provided, then it is	interpreted as in the
       "get()" method (q.v.)


	$raw = $rec->get("raw");
	$rendered = $rec->get("render");
	$trans = $rec->get("render;charset=latin1,utf8");
	$trans = $rec->get("render", "charset=latin1,utf8");

       This is the underlying method used by "render()"	and "raw()", and which
       in turn delegates to the	"ZOOM_record_get()" function of	the underlying
       ZOOM-C library.	Most applications will find it more natural to work
       with "render()" and "raw()".

       "get()" may be called with either one or	two arguments.	The two-
       argument	form is	syntactic sugar: the two arguments are simply joined
       with a semi-colon to make a single argument, so the third and fourth
       example invocations above are equivalent.  The second argument (or
       portion of the first argument following the semicolon) is used in the
       "type" argument of "ZOOM_record_get()", as described in This is useful
       primarily for invoking the character-set	transformation - in the
       examples	above, from ISO	Latin-1	to UTF-8 Unicode.

       clone() / destroy()

	$rec = $rs->record($i);
	$newrec	= $rec->clone();
	print $newrec->render();

       Usually,	it's convenient	that Record objects are	owned by their
       ResultSets and go away when the ResultSet is destroyed; but
       occasionally you	need a Record to outlive its parent and	destroy	it
       later, explicitly.  To do this, "clone()" the record, keep the new
       Record object that is returned, and "destroy()" it when it's no longer
       needed.	This is	only situation in which	a Record needs to be

       In general, method calls	throw an exception (of class
       "ZOOM::Exception") if anything goes wrong, so you don't need to test
       for success after each call.  Exceptions	are caught by enclosing	the
       main code in an "eval{}"	block and checking $@ on exit from that	block,
       as in the code-sample above.

       There are a small number	of exceptions to this rule: the	three record-
       fetching	methods	in the "ZOOM::ResultSet" class,	"record()",
       "record_immediate()", and "records()" can all return undefined values
       for legitimate reasons, under circumstances that	do not merit throwing
       an exception.  For this reason, the return values of these methods
       should be checked.  See the individual methods' documentation for

       An exception carries the	following pieces of information:

	   A numeric code that specifies the type of error.  This can be
	   checked for equality	with known values, so that intelligent
	   applications	can take appropriate action.

	   A human-readable message corresponding with the code.  This can be
	   shown to users, but its value should	not be tested, as it could
	   vary	in different versions or under different locales.

       additional information [optional]
	   A string containing information specific to the error-code.	For
	   example, when the error-code	is the BIB-1 diagnostic	109 ("Database
	   unavailable"), the additional information is	the name of the
	   database that the application tried to use.	For some error-codes,
	   there is no additional information at all; for some others, the
	   additional information is undefined and may just be an human-
	   readable string.

       diagnostic set [optional]
	   A short string specifying the diagnostic set	from which the error-
	   code	was drawn: for example,	"ZOOM" for a ZOOM-specific error such
	   as "ZOOM::Error::MEMORY" ("out of memory"), and "BIB-1" for a
	   Z39.50 error-code drawn from	the BIB-1 diagnostic set.

       In theory, the error-code should	be interpreted in the context of the
       diagnostic set from which it is drawn; in practice, nearly all errors
       are from	either the ZOOM	or BIB-1 diagnostic sets, and the codes	in
       those sets have been chosen so as not to	overlap, so the	diagnostic set
       can usually be ignored.

       See the description of the "Exception" class in the ZOOM	Abstract API



	die new	ZOOM::Exception($errcode, $errmsg, $addinfo, $diagset);

       Creates and returns a new Exception object with the specified error-
       code, error-message, additional information and diagnostic set.
       Applications will not in	general	need to	use this, but may find it
       useful to simulate ZOOM exceptions.  As is usual	with Perl, exceptions
       are thrown using	"die()".

       code() /	message() / addinfo() /	diagset()

	print "Error ",	$@->code(), ": ", $@->message(), "\n";
	print "(addinfo	'", $@->addinfo(), "', set '", $@->diagset(), "')\n";

       These methods, of no arguments, return the exception's error-code,
       error-message, additional information and diagnostic set	respectively.


	print $@->render();

       Returns a human-readable	rendition of an	exception.  The	"" operator is
       overloaded on the Exception class, so that an Exception used in a
       string context is automatically rendered.  Among	other consequences,
       this has	the useful result that a ZOOM application that died due	to an
       uncaught	exception will emit an informative message before exiting.

	$ss = $conn->scan('@attr 1=1003	a');
	$n = $ss->size();
	($term,	$occ) =	$ss->term($n-1);
	$rs = $conn->search_pqf('@attr 1=1003 "' . $term . "'");
	assert($rs->size() == $occ);

       A ScanSet represents a set of candidate search-terms returned from an
       index scan.  Its	sole purpose is	to provide access to those term, to
       the corresponding display terms,	and to the occurrence-counts of	the

       There is	no "new()" method nor any other	explicit constructor.  The
       only way	to create a new	ScanSet	is by using "scan()" on	a Connection.

       See the description of the "Scan	Set" class in the ZOOM Abstract	API at



	print "Found ",	$ss->size(), " terms\n";

       Returns the number of terms in the scan set.  In	general, this will be
       the scan-set size requested by the "number" option in the Connection on
       which the scan was performed [default 10], but it may be	fewer if the
       scan is close to	the end	of the index.

       term() /	display_term()

	$ss = $conn->scan('@attr 1=1004	whatever');
	($term,	$occurrences) =	$ss->term(0);
	($displayTerm, $occurrences2) =	$ss->display_term(0);
	assert($occurrences == $occurrences2);
	if (user_likes_the_look_of($displayTerm)) {
	    $rs	= $conn->search_pqf('@attr 1=4 "' . $term . '"');
	    assert($rs->size() == $occurrences);

       These methods return the	scanned	terms themselves.  "term()" returns
       the term	is a form suitable for submitting as part of a query, whereas
       "display_term()"	returns	it in a	form suitable for displaying to	a
       user.  Both versions also return	the number of occurrences of the term
       in the index, i.e. the number of	hits that will be found	if the term is
       subsequently used in a query.

       In most cases, the term and display term	will be	identical; however,
       they may	be different in	cases where punctuation	or case	is normalised,
       or where	identifiers rather than	the original document terms are


	print "scan status is ", $ss->option("scanStatus");

       Allows options to be set	into, and read from, a ScanSet,	just like the
       Connection class's "option()" method.  There is no "option_binary()"
       method for ScanSet objects.

       ScanSet options are also	described, though not particularly
       informatively, at



       Destroys	a ScanSet object, freeing its resources.  It is	an error to
       reuse a ScanSet that has	been "destroy()"ed.

	$p = $conn->package();
	$p->option(action => "specialUpdate");
	$p->option(recordIdOpaque => 145);
	$p->option(record => content_of("/tmp/record.xml"));

       This class represents an	Extended Services Package: an instruction to
       the server to do	something not covered by the core parts	of the Z39.50
       standard	(or the	equivalent in SRW or SRU).  Since the core protocols
       are read-only, such requests are	often used to make changes to the
       database, such as in the	record update example above.

       Requesting an extended service is a four-step process: first, create a
       package associated with the connection to the relevant database;
       second, set options on the package to instruct the server on what to
       do; third, send the package (which may result in	an exception being
       thrown if the server cannot execute the requested operations; and
       finally,	destroy	the package.

       Package options are listed at

       The particular options that have	meaning	are determined by the top-
       level operation string specified	as the argument	to "send()".  For
       example,	when the operation is "update" (the most commonly used
       extended	service), the "action" option may be set to any	of
       "recordInsert" (add a new record, failing if that record	already
       exists),	"recordDelete" (delete a record, failing if it is not in the
       database).  "recordReplace" (replace a record, failing if an old
       version is not already present) or "specialUpdate" (add a record,
       replacing any existing version that may be present).

       For update, the "record"	option should be set to	the full text of the
       XML record to added, deleted or replaced.  Depending on how the server
       is configured, it may extract the record's unique ID from the text
       (i.e. from a known element such as the 001 field	of a MARCXML record),
       or it may require the unique ID to passed in explicitly using the
       "recordIdOpaque"	option.

       Extended	services packages are not currently described in the ZOOM
       Abstract	API at They	will
       be added	in a forthcoming version, and will function much as those
       implemented in this module.



	$p->option(recordIdOpaque => "46696f6e61");

       Allows options to be set	into, and read from, a Package,	just like the
       Connection class's "option()" method.  There is no "option_binary()"
       method for Package objects.

       Package options are listed at



       Sends a package to the server associated	with the Connection that
       created it.  Problems are reported by throwing an exception.  The
       single parameter	indicates the operation	that the server	is being
       requested to perform, and controls the interpretation of	the package's
       options.	 Valid operations include:

	   Request a copy of a nominated object, e.g. place an ILL request.

	   Create a new	database, the name of which is specified by the
	   "databaseName" option.

	   Drop	an existing database, the name of which	is specified by	the
	   "databaseName" option.

	   Commit changes made to the database within a	transaction.

	   Modify the contents of the database by adding, deleting or
	   replacing records (as described above in the	overview of the
	   "ZOOM::Package" class).

	   I have no idea what this does.

       Although	the module is capable of making	all these requests, not	all
       servers are capable of executing	them.  Refusal is indicated by
       throwing	an exception.  Problems	may also be caused by lack of
       privileges; so "send()" must be used with caution, and is perhaps best
       wrapped in a clause that	checks for execptions, like so:

	eval { $p->send("create") };
	if ($@ && $@->isa("ZOOM::Exception")) {
	    print "Oops!  ", $@->message(), "\n";
	    return $@->code();



       Destroys	a Package object, freeing its resources.  It is	an error to
       reuse a Package that has	been "destroy()"ed.

	$q = new ZOOM::Query::CQL("creator=pike	and subject=unix");
	$q->sortby("1=4	>i 1=21	>s");
	$rs = $conn->search($q);

       "ZOOM::Query" is	a virtual base class from which	various	concrete
       subclasses can be derived.  Different subclasses	implement different
       types of	query.	The sole purpose of a Query object is to be used in a
       "search()" on a Connection; because PQF is such a common	special	case,
       the shortcut Connection method "search_pqf()" is	provided.

       The following Query subclasses are provided, each providing the same
       set of methods described	below:

	   Implements Prefix Query Format (PQF), also sometimes	known as
	   Prefix Query	Notation (PQN).	 This esoteric but rigorous and
	   expressive format is	described in the YAZ Manual at

	   Implements the Common Query Language	(CQL) of SRU, the
	   Search/Retrieve URL.	 CQL is	a much friendlier notation than	PQF,
	   using a simple infix	notation.  The queries are passed ``as is'' to
	   the server rather than being	compiled into a	Z39.50 Type-1 query,
	   so only CQL-compliant servers can support such querier.  CQL	is
	   described at and in a slight
	   out-of-date but nevertheless	useful tutorial	at

	   Implements CQL by compiling it on the client-side into a Z39.50
	   Type-1 (RPN)	query, and sending that.  This provides	essentially
	   the same functionality as "ZOOM::Query::CQL", but it	will work
	   against any standard	Z39.50 server rather than only against the
	   small subset	that support CQL natively.  The	drawback is that,
	   because the compilation is done on the client side, a configuration
	   file	is required to direct the mapping of CQL constructs such as
	   index names,	relations and modifiers	into Type-1 query attributes.
	   An example CQL configuration	file is	included in the	ZOOM-Perl
	   distribution, in the	file "samples/cql/"

	   Implements CCL by compiling it on the client-side into a Z39.50
	   Type-1 (RPN)	query, and sending that.  Because the compilation is
	   done	on the client side, a configuration file is required to	direct
	   the mapping of CCL constructs such as index names and boolean
	   operators into Type-1 query attributes.  An example CCL
	   configuration file is included in the ZOOM-Perl distribution, in
	   the file "samples/ccl/default.bib"

	   CCL is syntactically	very similar to	CQL, but much looser.  While
	   CQL is an entirely precise language in which	each possible query
	   has rigorously defined semantics, and is thus suitable for transfer
	   as part of a	protocol, CCL is best deployed as a human-facing UI

       See the description of the "Query" class	in the ZOOM Abstract API at



	$q = new ZOOM::Query::CQL('title=dinosaur');
	$q = new ZOOM::Query::PQF('@attr 1=4 dinosaur');

       Creates a new query object, compiling the query passed as its argument
       according to the	rules of the particular	query-type being instantiated.
       If compilation fails, an	exception is thrown.  Otherwise, the query may
       be passed to the	"Connection" method "search()".

	$conn->option(cqlfile => "samples/cql/");
	$q = new ZOOM::Query::CQL2RPN('title=dinosaur',	$conn);

       Note that for the "ZOOM::Query::CQL2RPN"	subclass, the Connection must
       also be passed into the constructor.  This is used for two purposes:
       first, its "cqlfile" option is used to find the CQL configuration file
       that directs the	translations into RPN; and second, if compilation
       fails, then diagnostic information is cached in the Connection and be
       retrieved using "$conn->errcode()" and related methods.

	$conn->option(cclfile => "samples/ccl/default.bib");
	# or
	$conn->option(cclqual => "ti u=4 s=pw\nab u=62 s=pw");
	$q = new ZOOM::Query::CCL2RPN('ti=dinosaur', $conn);

       For the "ZOOM::Query::CCL2RPN" subclass,	too, the Connection must be
       passed into the constructor, for	the same reasons as when client-side
       CQL compilation is used.	 The "cclqual" option, if defined, gives a CCL
       qualification specification inline; otherwise, the contents of the file
       named by	the "cclfile" option are used.


	$q->sortby("1=4	>i 1=21	>s");

       Sets a sort specification into the query, so that when a	"search()" is
       run on the query, the result is automatically sorted.  The sort
       specification language is the same as the "yaz" sort-specification type
       of the "ResultSet" method "sort()", described above.



       Destroys	a Query	object,	freeing	its resources.	It is an error to
       reuse a Query that has been "destroy()"ed.

	$o1 = new ZOOM::Options();
	$o1->option(user => "alf");
	$o2 = new ZOOM::Options();
	$o2->option(password =>	"fruit");
	$opts =	new ZOOM::Options($o1, $o2);
	$conn =	create ZOOM::Connection($opts);
	$conn->connect($host); # Uses the specified username and password

       Several classes of ZOOM objects carry their own sets of options,	which
       can be manipulated using	their "option()" method.  Sometimes, however,
       it's useful to deal with	the option sets	directly, and the
       "ZOOM::Options" class exists to enable this approach.

       Option sets are not currently described in the ZOOM Abstract API	at They	are an extension to
       that specification.



	$o1 = new ZOOM::Options();
	$o1and2	= new ZOOM::Options($o1);
	$o3 = new ZOOM::Options();
	$o1and3and4 = new ZOOM::Options($o1, $o3);

       Creates and returns a new option	set.  One or two (but no more)
       existing	option sets may	be passed as arguments,	in which case they
       become ``parents'' of the new set, which	thereby	``inherits'' their
       options,	the values of the first	parent overriding those	of the second
       when both have a	value for the same key.	 An option set that inherits
       from a parent that has its own parents also inherits the	grandparent's
       options,	and so on.

       option()	/ option_binary()

	$o->option(preferredRecordSyntax => "usmarc");
	$o->option_binary(iconBlob => "foo\0bar");
	die if length($o->option_binary("iconBlob") != 7);

       These methods are used to get and set options within a set, and behave
       the same	way as the same-named "Connection" methods - see above.	 As
       with the	"Connection" methods, values passed to and retrieved using
       "option()" are interpreted as NUL-terminated, while those passed	to and
       retrieved from "option_binary()"	are binary-clean.


	$o->option(x =>	"T");
	$o->option(y =>	"F");
	assert($o->bool("x", 1));
	assert(!$o->bool("y", 1));
	assert($o->bool("z", 1));

       The first argument is a key, and	the second is a	default	value.
       Returns the value associated with the specified key as a	boolean, or
       the default value if the	key has	not been set.  The values "T" (upper
       case) and 1 are considered true;	all other values (including "t"	(lower
       case) and non-zero integers other than one) are considered false.

       This method is provided in ZOOM-C because in a statically typed
       language	it's convenient	to have	the result returned as an easy-to-test
       type.  In a dynamically typed language such as Perl, this problem
       doesn't arise, so "bool()" is nearly useless; but it is made available
       in case applications need to duplicate the idiosyncratic	interpretation
       of truth	and falsehood and ZOOM-C uses.


	$o->option(x =>	"012");
	assert($o->int("x", 20)	== 12);
	assert($o->int("y", 20)	== 20);

       Returns the value associated with the specified key as an integer, or
       the default value if the	key has	not been set.  See the description of
       "bool()"	for why	you almost certainly don't want	to use this.


	$o->set_int(x => "29");

       Sets the	value of the specified option as an integer.  Of course, Perl
       happily converts	strings	to integers on its own,	so you can just	use
       "option()" for this, but	"set_int()" is guaranteed to use the same
       string-to-integer conversion as ZOOM-C does, which might	occasionally
       be useful.  Though I can't imagine how.


	sub cb {
	    ($udata, $key) = @;
	    return "$udata-$key-$udata";
	$o->set_callback(\&cb, "xyz");
	assert($o->option("foo") eq "xyz-foo-xyz");

       This method allows a callback function to be installed in an option
       set, so that the	values of options can be calculated algorithmically
       rather than, as usual, looked up	in a table.  Along with	the callback
       function	itself,	an additional datum is provided: when an option	is
       subsequently looked up, this datum is passed to the callback function
       along with the key; and its return value	is returned to the caller as
       the value of the	option.

       Warning.	 Although it ought to be possible to specify callback function
       using the "\&name" syntax above,	or a literal "sub { code }" code
       reference, the complexities of the Perl-internal	memory management
       system mean that	the function must currently be specified as a string
       containing the fully-qualified name, e.g. "main::cb".>

       Warning.	 The current implementation of the this	method leaks memory,
       not only	when the callback is installed,	but on every occasion that it
       is consulted to look up an option value.



       Destroys	an Options object, freeing its resources.  It is an error to
       reuse an	Options	object that has	been "destroy()"ed.

       The ZOOM	module provides	two enumerations that list possible return
       values from particular functions.  They are described in	the following

	if ($@->code() == ZOOM::Error::QUERY_PQF) {
	    return "your query was not accepted";

       This class provides a set of manifest constants representing some of
       the possible error codes	that can be raised by the ZOOM module.	The
       methods that return error-codes are "ZOOM::Exception::code()",
       "ZOOM::Connection::error_x()" and "ZOOM::Connection::errcode()".

       The "ZOOM::Error" class provides	the constants "NONE", "CONNECT",
       "CLONE",	"PACKAGE", "SCANTERM" and "LOGLEVEL", each of which specifies
       a client-side error.  These codes constitute the	"ZOOM" diagnostic set.

       Since errors may	also be	diagnosed by the server, and returned to the
       client, error codes may also take values	from the BIB-1 diagnostic set
       of Z39.50, listed at the	Z39.50 Maintenance Agency's web-site at

       All error-codes,	whether	client-side from the "ZOOM::Error" enumeration
       or server-side from the BIB-1 diagnostic	set, can be translated into
       human-readable messages by passing them to the "ZOOM::diag_str()"
       utility function.

	if ($conn->last_event()	== ZOOM::Event::CONNECT) {
	    print "Connected!\n";

       In applications that need it - mostly complex multiplexing applications
       - The "ZOOM::Connection::last_event()" method is	used to	return an
       indication of the last event that occurred on a particular connection.
       It always returns a value drawn from this enumeration, that is, one of

       See the section below on	asynchronous applications.

	ZOOM::Log::log("myapp",	"starting up with pid ", $$);

       Logging facilities are provided by a set	of functions in	the
       "ZOOM::Log" module.  Note that "ZOOM::Log" is not a class, and it is
       not possible to create "ZOOM::Log" objects: the API is imperative,
       reflecting that of the underlying YAZ logging facilities.  Although
       there are nine logging functions	altogether, you	can ignore nearly all
       of them:	most applications that use logging will	begin by calling
       "mask_str()" and	"init_level()" once each, as above, and	will then
       repeatedly call "log()".

	$level = ZOOM::Log::mask_str("zoom,myapp,-warn");

       Returns an integer corresponding	to the log-level specified by the
       parameter.  This	is a string of zero or more comma-separated module-
       names, each indicating an individual module to be either	added to the
       default log-level or removed from it (for those components prefixed by
       a minus-sign).  The names may be	those of either	standard YAZ-logging
       modules such as "fatal",	"debug"	and "warn", or custom modules such as
       "myapp" in the example above.  The module "zoom"	requests logging from
       the ZOOM	module itself, which may be helpful for	debugging.

       Note that calling this function does not	in any way change the logging
       state: it merely	returns	a value.  To change the	state, this value must
       be passed to "init_level()".

	$level = ZOOM::Log::module_level("zoom");
	ZOOM::Log::log($level, "all systems clear: thrusters invogriated");

       Returns the integer corresponding to the	single log-level specified as
       the parameter, or zero if that level has	not been registered by a prior
       call to "mask_str()".  Since "log()" accepts either a numeric log-level
       or a string, there is no	reason to call this function; but, what	the
       heck, maybe you enjoy that kind of thing.  Who are we to	judge?


       Initialises the log-level to the	specified integer, which is a bitmask
       of values, typically as returned	from "mask_str()".  All	subsequent
       calls to	"log()"	made with a log-level that matches one of the bits in
       this mask will result in	a log-message being emitted.  All logging can
       be turned off by	calling	init_level(0).


       Initialises a prefix string to be included in all log-messages.


       Initialises the output file to be used for logging: subsequent log-
       messages	are written to the nominated file.  If this function is	not
       called, log-messages are	written	to the standard	error stream.

	ZOOM::Log::init($level,	$0, "/tmp/myapp.log");

       Initialises the log-level, the logging prefix and the logging output
       file in a single	operation.

	ZOOM::Log::time_format("%Y-%m-%d %H:%M:%S");

       Sets the	format in which	log-messages' timestamps are emitted, by means
       of a format-string like that used in the	C function "strftime()".  The
       example above emits year, month,	day, hours, minutes and	seconds	in
       big-endian order, such that timestamps can be sorted lexicographically.

       (This doesn't seem to work, so I	won't bother describing	it.)

	ZOOM::Log::log(8192, "reducing to warp-factor $wf");
	ZOOM::Log::log("myapp",	"starting up with pid ", $$);

       Provided	that the first argument, log-level, is among the modules
       previously established by "init_level()", this function emits a log-
       message made up of a timestamp, the prefix supplied to "init_prefix()",
       if any, and the concatenation of	all arguments after the	first.	The
       message is written to the standard output stream, or to the file
       previous	specified by "init_file()" if this has been called.

       The log-level argument may be either a numeric value, as	returned from
       "module_level()", or a string containing	the module name.

       Although	asynchronous applications are conceptually complex, the	ZOOM
       support for them	is provided through a very simple interface,
       consisting of one option	("async"), one function	("ZOOM::event()"), one
       Connection method ("last_event()" and an	enumeration ("ZOOM::Event").

       The approach is as follows:

	   Create several connections to the various servers, each of them
	   having the option "async" set, and with whatever additional options
	   are required	- e.g. the piggyback retrieval record-count can	be set
	   so that records will	be returned in search responses.

	   Send	searches to the	connections, request records, etc.

       Event harvesting
	   Repeatedly call "ZOOM::event()" to discover what responses are
	   being received from the servers.  Each time this function returns,
	   it indicates	which of the connections has fired; this connection
	   can then be interrogated with the "last_event()" method to discover
	   what	event has occurred, and	the return value - an element of the
	   "ZOOM::Event" enumeration - can be tested to	determine what to do
	   next.  For example, the "ZEND" event	indicates that no further
	   operations are outstanding on the connection, so any	fetched
	   records can now be immediately obtained.

       Here is a very short program (omitting all error-checking!) which
       demonstrates this process.  It parallel-searches	three servers (or more
       of you add them the list), displaying the first record in the result-
       set of each server as soon as it	becomes	available.

	use ZOOM;
	@servers = ('',
	for ($i	= 0; $i	< @servers; $i++) {
	    $z[$i] = new ZOOM::Connection($servers[$i],	0,
					  async	=> 1, #	asynchronous mode
					  count	=> 1, #	piggyback retrieval count
					  preferredRecordSyntax	=> "usmarc");
	    $r[$i] = $z[$i]->search_pqf("mineral");
	while (($i = ZOOM::event(\@z)) != 0) {
	    $ev	= $z[$i-1]->last_event();
	    print("connection ", $i-1, ": ", ZOOM::event_str($ev), "\n");
	    if ($ev == ZOOM::Event::ZEND) {
		$size =	$r[$i-1]->size();
		print "connection ", $i-1, ": $size hits\n";
		print $r[$i-1]->record(0)->render()
		    if $size > 0;

       The ZOOM	abstract API,

       The "Net::Z3950::ZOOM" module, included in the same distribution	as
       this one.

       The "Net::Z3950"	module,	which this one supersedes.

       The documentation for the ZOOM-C	module of the YAZ Toolkit, which this
       module is built on.  Specifically, its lists of options are useful.

       The BIB-1 diagnostic set	of Z39.50,

       Mike Taylor, <>

       Copyright (C) 2005-2014 by Index	Data.

       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself, either Perl	version	5.8.4 or, at
       your option, any	later version of Perl 5	you may	have available.

perl v5.32.0			  2014-01-21			       ZOOM(3)


Want to link to this manual page? Use this URL:

home | help