1 # $Id: ZOOM.pm,v 1.38 2008-06-09 13:49:32 mike Exp $
3 package Net::Z3950::ZOOM;
12 XSLoader::load('Net::Z3950::ZOOM', $VERSION);
14 my($vs, $ss) = ("x" x 100, "x" x 100); # allocate space for these strings
15 my $version = Net::Z3950::ZOOM::yaz_version($vs, $ss);
16 if ($version < 0x020132 && ! -f "/tmp/ignore-ZOOM-YAZ-version-mismatch") {
19 ZOOM-Perl requires at least version 2.1.50 of YAZ, but is currently
20 running against only version $vs (sys-string '$ss').
21 Some things may not work.
25 # The only thing this module does is define the following constants,
26 # which MUST BE KEPT SYNCHRONISED with the definitions in <yaz/zoom.h>
28 # Error codes, as returned from connection_error()
30 sub ERROR_CONNECT { 10000 }
31 sub ERROR_MEMORY { 10001 }
32 sub ERROR_ENCODE { 10002 }
33 sub ERROR_DECODE { 10003 }
34 sub ERROR_CONNECTION_LOST { 10004 }
35 sub ERROR_INIT { 10005 }
36 sub ERROR_INTERNAL { 10006 }
37 sub ERROR_TIMEOUT { 10007 }
38 sub ERROR_UNSUPPORTED_PROTOCOL { 10008 }
39 sub ERROR_UNSUPPORTED_QUERY { 10009 }
40 sub ERROR_INVALID_QUERY { 10010 }
41 sub ERROR_CQL_PARSE { 10011 }
42 sub ERROR_CQL_TRANSFORM { 10012 }
43 sub ERROR_CCL_CONFIG { 10013 }
44 sub ERROR_CCL_PARSE { 10014 }
46 # Event types, as returned from connection_last_event()
48 sub EVENT_CONNECT { 1 }
49 sub EVENT_SEND_DATA { 2 }
50 sub EVENT_RECV_DATA { 3 }
51 sub EVENT_TIMEOUT { 4 }
52 sub EVENT_UNKNOWN { 5 }
53 sub EVENT_SEND_APDU { 6 }
54 sub EVENT_RECV_APDU { 7 }
55 sub EVENT_RECV_RECORD { 8 }
56 sub EVENT_RECV_SEARCH { 9 }
57 sub EVENT_END { 10 } # In YAZ 2.1.17 and later
59 # CCL error-codes, which are in a different space from the ZOOM errors
61 sub CCL_ERR_TERM_EXPECTED { 1 }
62 sub CCL_ERR_RP_EXPECTED { 2 }
63 sub CCL_ERR_SETNAME_EXPECTED { 3 }
64 sub CCL_ERR_OP_EXPECTED { 4 }
65 sub CCL_ERR_BAD_RP { 5 }
66 sub CCL_ERR_UNKNOWN_QUAL { 6 }
67 sub CCL_ERR_DOUBLE_QUAL { 7 }
68 sub CCL_ERR_EQ_EXPECTED { 8 }
69 sub CCL_ERR_BAD_RELATION { 9 }
70 sub CCL_ERR_TRUNC_NOT_LEFT { 10 }
71 sub CCL_ERR_TRUNC_NOT_BOTH { 11 }
72 sub CCL_ERR_TRUNC_NOT_RIGHT { 12 }
77 Net::Z3950::ZOOM - Perl extension for invoking the ZOOM-C API.
82 $conn = Net::Z3950::ZOOM::connection_new($host, $port);
83 $errcode = Net::Z3950::ZOOM::connection_error($conn, $errmsg, $addinfo);
84 Net::Z3950::ZOOM::connection_option_set($conn, databaseName => "foo");
89 This module provides a simple thin-layer through to the ZOOM-C
90 functions in the YAZ toolkit for Z39.50 and SRW/U communication. You
91 should not be using this very nasty, low-level API. You should be
92 using the C<ZOOM> module instead, which implements a nice, Perlish API
93 on top of this module, conformant to the ZOOM Abstract API described at
94 http://zoom.z3950.org/api/
96 To enforce the don't-use-this-module prohibition, I am not even going
97 to document it. If you really, really, really want to use it, then it
98 pretty much follows the API described in the ZOOM-C documentation at
99 http://www.indexdata.dk/yaz/doc/zoom.tkl
101 The only additional (non-ZOOM-C) function provided by this module is
102 C<event_str()>, which takes as its argument an event code such as
103 C<Net::Z3950::ZOOM::EVENT_SEND_APDU>, and returns a corresponding
111 if ($code == EVENT_NONE) {
113 } elsif ($code == EVENT_CONNECT) {
115 } elsif ($code == EVENT_SEND_DATA) {
117 } elsif ($code == EVENT_RECV_DATA) {
118 return "receive data";
119 } elsif ($code == EVENT_TIMEOUT) {
121 } elsif ($code == EVENT_UNKNOWN) {
123 } elsif ($code == EVENT_SEND_APDU) {
125 } elsif ($code == EVENT_RECV_APDU) {
126 return "receive apdu";
127 } elsif ($code == EVENT_RECV_RECORD) {
128 return "receive record";
129 } elsif ($code == EVENT_RECV_SEARCH) {
130 return "receive search";
131 } elsif ($code == EVENT_END) {
134 return "impossible event " . $code;
138 # Switch API variant depending on $type. This works because the
139 # get_string() and get_binary() functions have different returns
140 # types, one of which is implemented as a NUL-terminated string and
141 # the other as a pointer-and-length structure.
143 # Some Z39.50 servers, when asked for an OPAC-format record in the
144 # case where no circulation information is available, will return a
145 # USMARC record rather than an OPAC record containing only a
146 # bibliographic part. This non-OPAC records is not recognised by the
147 # underlying record_get() code in ZOOM-C, which ends up returning a
148 # null pointer. To make life a little less painful when dealing with
149 # such servers until ZOOM-C is fixed, this code recognises the
150 # wrong-record-syntax case and returns the XML for the bibliographic
154 my($rec, $type) = @_;
156 my $simpletype = $type;
157 $simpletype =~ s/;.*//;
158 warn "record_get('$rec', '$simpletype' -> '$type')\n";
159 if (grep { $type eq $_ } qw(database syntax schema)) {
160 return record_get_string($rec, $type);
162 my $val = record_get_binary($rec, $type);
163 if ($simpletype eq "opac" && !defined $val) {
165 if ($newtype !~ s/.*?;/xml;/) {
168 warn "fallback('$rec', '$newtype')\n";
169 $val = record_get_binary($rec, $newtype);
178 The C<ZOOM> module, included in the same distribution as this one.
182 Mike Taylor, E<lt>mike@indexdata.comE<gt>
184 =head1 COPYRIGHT AND LICENCE
186 Copyright (C) 2005 by Index Data.
188 This library is free software; you can redistribute it and/or modify
189 it under the same terms as Perl itself, either Perl version 5.8.4 or,
190 at your option, any later version of Perl 5 you may have available.