lib/Net/Z3950/ZOOM.pm

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