SimpleServer.pm

   1 ##
   2 ##  Copyright (c) 2000-2006, Index Data.
   3 ##
   4 ##  Permission to use, copy, modify, distribute, and sell this software and
   5 ##  its documentation, in whole or in part, for any purpose, is hereby granted,
   6 ##  provided that:
   7 ##
   8 ##  1. This copyright and permission notice appear in all copies of the
   9 ##  software and its documentation. Notices of copyright or attribution
  10 ##  which appear at the beginning of any file must remain unchanged.
  11 ##
  12 ##  2. The name of Index Data or the individual authors may not be used to
  13 ##  endorse or promote products derived from this software without specific
  14 ##  prior written permission.
  15 ##
  16 ##  THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND,
  17 ##  EXPRESS, IMPLIED, OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
  18 ##  WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
  19 ##  IN NO EVENT SHALL INDEX DATA BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
  20 ##  INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES
  21 ##  WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR
  22 ##  NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
  23 ##  LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
  24 ##  OF THIS SOFTWARE.
  25 ##
  26 ##
  27
  28 ## $Id: SimpleServer.pm,v 1.40 2007-08-20 11:06:09 mike Exp $
  29
  30 package Net::Z3950::SimpleServer;
  31
  32 use strict;
  33 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
  34 use Carp;
  35
  36 require Exporter;
  37 require DynaLoader;
  38 require AutoLoader;
  39
  40 @ISA = qw(Exporter AutoLoader DynaLoader);
  41 @EXPORT = qw( );
  42 $VERSION = '1.07';
  43
  44 bootstrap Net::Z3950::SimpleServer $VERSION;
  45
  46 # Preloaded methods go here.
  47
  48 my $count = 0;
  49
  50 sub new {
  51         my $class = shift;
  52         my %args = @_;
  53         my $self = \%args;
  54
  55         if ($count) {
  56                 carp "SimpleServer.pm: WARNING: Multithreaded server unsupported";
  57         }
  58         $count = 1;
  59
  60         croak "SimpleServer.pm: ERROR: Unspecified search handler" unless defined($self->{SEARCH});
  61         croak "SimpleServer.pm: ERROR: Unspecified fetch handler" unless defined($self->{FETCH});
  62
  63         bless $self, $class;
  64         return $self;
  65 }
  66
  67
  68 sub launch_server {
  69         my $self = shift;
  70         my @args = @_;
  71
  72         ### This modal internal interface, in which we set a bunch of
  73         #   globals and then call start_server(), is asking for
  74         #   trouble.  Instead, we should just pass the $self object
  75         #   as a parameter into start_server().
  76         if (defined($self->{GHANDLE})) {
  77                 set_ghandle($self->{GHANDLE});
  78         }
  79         if (defined($self->{INIT})) {
  80                 set_init_handler($self->{INIT});
  81         }
  82         set_search_handler($self->{SEARCH});
  83         set_fetch_handler($self->{FETCH});
  84         if (defined($self->{CLOSE})) {
  85                 set_close_handler($self->{CLOSE});
  86         }
  87         if (defined($self->{PRESENT})) {
  88                 set_present_handler($self->{PRESENT});
  89         }
  90         if (defined($self->{SCAN})) {
  91                 set_scan_handler($self->{SCAN});
  92         }
  93         if (defined($self->{SORT})) {
  94                 set_sort_handler($self->{SORT});
  95         }
  96         if (defined($self->{EXPLAIN})) {
  97                 set_explain_handler($self->{EXPLAIN});
  98         }
  99
 100         start_server(@args);
 101 }
 102
 103
 104 # Register packages that we will use in translated RPNs
 105 package Net::Z3950::RPN::Node;
 106 package Net::Z3950::APDU::Query;
 107 our @ISA = qw(Net::Z3950::RPN::Node);
 108 package Net::Z3950::APDU::OID;
 109 package Net::Z3950::RPN::And;
 110 our @ISA = qw(Net::Z3950::RPN::Node);
 111 package Net::Z3950::RPN::Or;
 112 our @ISA = qw(Net::Z3950::RPN::Node);
 113 package Net::Z3950::RPN::AndNot;
 114 our @ISA = qw(Net::Z3950::RPN::Node);
 115 package Net::Z3950::RPN::Term;
 116 our @ISA = qw(Net::Z3950::RPN::Node);
 117 package Net::Z3950::RPN::RSID;
 118 our @ISA = qw(Net::Z3950::RPN::Node);
 119 package Net::Z3950::RPN::Attributes;
 120 package Net::Z3950::RPN::Attribute;
 121
 122
 123 # Utility method for re-rendering Type-1 query back down to PQF
 124 package Net::Z3950::RPN::Node;
 125
 126 sub toPQF {
 127     my $this = shift();
 128     my $class = ref $this;
 129
 130     if ($class eq "Net::Z3950::APDU::Query") {
 131         my $res = "";
 132         my $set = $this->{attributeSet};
 133         $res .= "\@attrset $set " if defined $set;
 134         return $res . $this->{query}->toPQF();
 135     } elsif ($class eq "Net::Z3950::RPN::Or") {
 136         return '@or ' . $this->[0]->toPQF() . ' ' . $this->[1]->toPQF();
 137     } elsif ($class eq "Net::Z3950::RPN::And") {
 138         return '@and ' . $this->[0]->toPQF() . ' ' . $this->[1]->toPQF();
 139     } elsif ($class eq "Net::Z3950::RPN::AndNot") {
 140         return '@not ' . $this->[0]->toPQF() . ' ' . $this->[1]->toPQF();
 141     } elsif ($class eq "Net::Z3950::RPN::RSID") {
 142         return '@set ' . $this->{id};
 143     } elsif ($class ne "Net::Z3950::RPN::Term") {
 144         die "unknown PQF node-type '$class'";
 145     }
 146
 147     my $res = "";
 148     foreach my $attr (@{ $this->{attributes} }) {
 149         $res .= "\@attr ";
 150         my $set = $attr->{attributeSet};
 151         $res .= "$set " if defined $set;
 152         $res .= $attr->{attributeType} . "=" . $attr->{attributeValue} . " ";
 153     }
 154
 155     return $res . $this->{term};
 156 }
 157
 158
 159 # Must revert to original package for Autoloader's benefit
 160 package Net::Z3950::SimpleServer;
 161
 162
 163 # Autoload methods go after =cut, and are processed by the autosplit program.
 164
 165 1;
 166 __END__
 167 # Below is the stub of documentation for your module. You better edit it!
 168
 169 =head1 NAME
 170
 171 Net::Z3950::SimpleServer - Simple Perl API for building Z39.50 servers.
 172
 173 =head1 SYNOPSIS
 174
 175   use Net::Z3950::SimpleServer;
 176
 177   sub my_search_handler {
 178         my $args = shift;
 179
 180         my $set_id = $args->{SETNAME};
 181         my @database_list = @{ $args->{DATABASES} };
 182         my $query = $args->{QUERY};
 183
 184         ## Perform the query on the specified set of databases
 185         ## and return the number of hits:
 186
 187         $args->{HITS} = $hits;
 188   }
 189
 190   sub my_fetch_handler {        # Get a record for the user
 191         my $args = shift;
 192
 193         my $set_id = $args->{SETNAME};
 194
 195         my $record = fetch_a_record($args->{OFFSET});
 196
 197         $args->{RECORD} = $record;
 198         if (number_of_hits() == $args->{OFFSET}) {      ## Last record in set?
 199                 $args->{LAST} = 1;
 200         } else {
 201                 $args->{LAST} = 0;
 202         }
 203   }
 204
 205   ## Register custom event handlers:
 206   my $z = new Net::Z3950::SimpleServer(GHANDLE = $someObject,
 207                                        INIT   =>  \&my_init_handler,
 208                                        CLOSE  =>  \&my_close_handler,
 209                                        SEARCH =>  \&my_search_handler,
 210                                        FETCH  =>  \&my_fetch_handler);
 211
 212   ## Launch server:
 213   $z->launch_server("ztest.pl", @ARGV);
 214
 215 =head1 DESCRIPTION
 216
 217 The SimpleServer module is a tool for constructing Z39.50 "Information
 218 Retrieval" servers in Perl. The module is easy to use, but it
 219 does help to have an understanding of the Z39.50 query
 220 structure and the construction of structured retrieval records.
 221
 222 Z39.50 is a network protocol for searching remote databases and
 223 retrieving the results in the form of structured "records". It is widely
 224 used in libraries around the world, as well as in the US Federal Government.
 225 In addition, it is generally useful whenever you wish to integrate a number
 226 of different database systems around a shared, asbtract data model.
 227
 228 The model of the module is simple: It implements a "generic" Z39.50
 229 server, which invokes callback functions supplied by you to search
 230 for content in your database. You can use any tools available in
 231 Perl to supply the content, including modules like DBI and
 232 WWW::Search.
 233
 234 The server will take care of managing the network connections for
 235 you, and it will spawn a new process (or thread, in some
 236 environments) whenever a new connection is received.
 237
 238 The programmer can specify subroutines to take care of the following type
 239 of events:
 240
 241   - Initialize request
 242   - Search request
 243   - Present request
 244   - Fetching of records
 245   - Scan request (browsing)
 246   - Closing down connection
 247
 248 Note that only the Search and Fetch handler functions are required.
 249 The module can supply default responses to the other on its own.
 250
 251 After the launching of the server, all control is given away from
 252 the Perl script to the server. The server calls the registered
 253 subroutines to field incoming requests from Z39.50 clients.
 254
 255 A reference to an anonymous hash is passed to each handler. Some of
 256 the entries of these hashes are to be considered input and others
 257 output parameters.
 258
 259 The Perl programmer specifies the event handlers for the server by
 260 means of the SimpleServer object constructor
 261
 262   my $z = new Net::Z3950::SimpleServer(
 263                         INIT    =>      \&my_init_handler,
 264                         CLOSE   =>      \&my_close_handler,
 265                         SEARCH  =>      \&my_search_handler,
 266                         PRESENT =>      \&my_present_handler,
 267                         SCAN    =>      \&my_scan_handler,
 268                         FETCH   =>      \&my_fetch_handler,
 269                         EXPLAIN =>      \&my_explain_handler);
 270
 271 In addition, the arguments to the constructor may include GHANDLE, a
 272 global handle which is made available to each invocation of every
 273 callback function.  This is typically a reference to either a hash or
 274 an object.
 275
 276 If you want your SimpleServer to start a thread (threaded mode) to
 277 handle each incoming Z39.50 request instead of forking a process
 278 (forking mode), you need to register the handlers by symbol rather
 279 than by code reference. Thus, in threaded mode, you will need to
 280 register your handlers this way:
 281
 282   my $z = new Net::Z3950::SimpleServer(
 283                         INIT    =>      "my_package::my_init_handler",
 284                         CLOSE   =>      "my_package::my_close_handler",
 285                         ....
 286                         ....          );
 287
 288 where my_package is the Perl package in which your handler is
 289 located.
 290
 291 After the custom event handlers are declared, the server is launched
 292 by means of the method
 293
 294   $z->launch_server("MyServer.pl", @ARGV);
 295
 296 Notice, the first argument should be the name of your server
 297 script (for logging purposes), while the rest of the arguments
 298 are documented in the YAZ toolkit manual: The section on
 299 application invocation: <http://www.indexdata.dk/yaz/yaz-7.php>
 300
 301 In particular, you need to use the -T switch to start your SimpleServer
 302 in threaded mode.
 303
 304 =head2 Init handler
 305
 306 The init handler is called whenever a Z39.50 client is attempting
 307 to logon to the server. The exchange of parameters between the
 308 server and the handler is carried out via an anonymous hash reached
 309 by a reference, i.e.
 310
 311   $args = shift;
 312
 313 The argument hash passed to the init handler has the form
 314
 315   $args = {
 316                                     ## Response parameters:
 317
 318              IMP_ID    =>  "",      ## Z39.50 Implementation ID
 319              IMP_NAME  =>  "",      ## Z39.50 Implementation name
 320              IMP_VER   =>  "",      ## Z39.50 Implementation version
 321              ERR_CODE  =>  0,       ## Error code, cnf. Z39.50 manual
 322              ERR_STR   =>  "",      ## Error string (additional info.)
 323              USER      =>  "xxx"    ## If Z39.50 authentication is used,
 324                                     ## this member contains user name
 325              PASS      =>  "yyy"    ## Under same conditions, this member
 326                                     ## contains the password in clear text
 327              GHANDLE   =>  $obj     ## Global handler specified at creation
 328              HANDLE    =>  undef    ## Handler of Perl data structure
 329           };
 330
 331 The HANDLE member can be used to store any scalar value which will then
 332 be provided as input to all subsequent calls (ie. for searching, record
 333 retrieval, etc.). A common use of the handle is to store a reference to
 334 a hash which may then be used to store session-specific parameters.
 335 If you have any session-specific information (such as a list of
 336 result sets or a handle to a back-end search engine of some sort),
 337 it is always best to store them in a private session structure -
 338 rather than leaving them in global variables in your script.
 339
 340 The Implementation ID, name and version are only really used by Z39.50
 341 client developers to see what kind of server they're dealing with.
 342 Filling these in is optional.
 343
 344 The ERR_CODE should be left at 0 (the default value) if you wish to
 345 accept the connection. Any other value is interpreted as a failure
 346 and the client will be shown the door, with the code and the
 347 associated additional information, ERR_STR returned.
 348
 349 =head2 Search handler
 350
 351 Similarly, the search handler is called with a reference to an anony-
 352 mous hash. The structure is the following:
 353
 354   $args = {
 355                                     ## Request parameters:
 356
 357              GHANDLE   =>  $obj     ## Global handler specified at creation
 358              HANDLE    =>  ref,     ## Your session reference.
 359              SETNAME   =>  "id",    ## ID of the result set
 360              REPL_SET  =>  0,       ## Replace set if already existing?
 361              DATABASES =>  ["xxx"], ## Reference to a list of data-
 362                                     ## bases to search
 363              QUERY     =>  "query", ## The query expression
 364              RPN       =>  $obj,    ## Reference to a Net::Z3950::APDU::Query
 365
 366                                     ## Response parameters:
 367
 368              ERR_CODE  =>  0,       ## Error code (0=Succesful search)
 369              ERR_STR   =>  "",      ## Error string
 370              HITS      =>  0        ## Number of matches
 371           };
 372
 373 Note that a search which finds 0 hits is considered successful in
 374 Z39.50 terms - you should only set the ERR_CODE to a non-zero value
 375 if there was a problem processing the request. The Z39.50 standard
 376 provides a comprehensive list of standard diagnostic codes, and you
 377 should use these whenever possible.
 378
 379 The QUERY is a tree-structure of terms combined by operators, the
 380 terms being qualified by lists of attributes. The query is presented
 381 to the search function in the Prefix Query Format (PQF) which is
 382 used in many applications based on the YAZ toolkit. The full grammar
 383 is described in the YAZ manual.
 384
 385 The following are all examples of valid queries in the PQF.
 386
 387         dylan
 388
 389         "bob dylan"
 390
 391         @or "dylan" "zimmerman"
 392
 393         @set Result-1
 394
 395         @or @and bob dylan @set Result-1
 396
 397         @and @attr 1=1 "bob dylan" @attr 1=4 "slow train coming"
 398
 399         @attrset @attr 4=1 @attr 1=4 "self portrait"
 400
 401 You will need to write a recursive function or something similar to
 402 parse incoming query expressions, and this is usually where a lot of
 403 the work in writing a database-backend happens. Fortunately, you don't
 404 need to support anymore functionality than you want to. For instance,
 405 it is perfectly legal to not accept boolean operators, but you SHOULD
 406 try to return good error codes if you run into something you can't or
 407 won't support.
 408
 409 A more convenient alternative to the QUERY member may be the RPN
 410 member, which is a reference to a Net::Z3950::APDU::Query object
 411 representing the RPN query tree.  The structure of that object is
 412 supposed to be self-documenting, but here's a brief summary of what
 413 you get:
 414
 415 =over 4
 416
 417 =item *
 418
 419 C<Net::Z3950::APDU::Query> is a hash with two fields:
 420
 421 Z<>
 422
 423 =over 4
 424
 425 =item C<attributeSet>
 426
 427 Optional.  If present, it is a reference to a
 428 C<Net::Z3950::APDU::OID>.  This is a string of dot-separated integers
 429 representing the OID of the query's top-level attribute set.
 430
 431 =item C<query>
 432
 433 Mandatory: a refererence to the RPN tree itself.
 434
 435 =back
 436
 437 =item *
 438
 439 Each node of the tree is an object of one of the following types:
 440
 441 Z<>
 442
 443 =over 4
 444
 445 =item C<Net::Z3950::RPN::And>
 446
 447 =item C<Net::Z3950::RPN::Or>
 448
 449 =item C<Net::Z3950::RPN::AndNot>
 450
 451 These three classes are all arrays of two elements, each of which is a
 452 node of one of the above types.
 453
 454 =item C<Net::Z3950::RPN::Term>
 455
 456 See below for details.
 457
 458 =item C<Net::Z3950::RPN::RSID>
 459
 460 A reference to a result-set ID indicating a previous search.  The ID
 461 of the result-set is in the C<id> element.
 462
 463 =back
 464
 465 =back
 466
 467 =over 4
 468
 469 =item *
 470
 471 C<Net::Z3950::RPN::Term> is a hash with two fields:
 472
 473 Z<>
 474
 475 =over 4
 476
 477 =item C<term>
 478
 479 A string containing the search term itself.
 480
 481 =item C<attributes>
 482
 483 A reference to a C<Net::Z3950::RPN::Attributes> object.
 484
 485 =back
 486
 487 =item *
 488
 489 C<Net::Z3950::RPN::Attributes> is an array of references to
 490 C<Net::Z3950::RPN::Attribute> objects.  (Note the plural/singular
 491 distinction.)
 492
 493 =item *
 494
 495 C<Net::Z3950::RPN::Attribute> is a hash with three elements:
 496
 497 Z<>
 498
 499 =over 4
 500
 501 =item C<attributeSet>
 502
 503 Optional.  If present, it is dot-separated OID string, as above.
 504
 505 =item C<attributeType>
 506
 507 An integer indicating the type of the attribute - for example, under
 508 the BIB-1 attribute set, type 1 indicates a ``use'' attribute, type 2
 509 a ``relation'' attribute, etc.
 510
 511 =item C<attributeValue>
 512
 513 An integer or string indicating the value of the attribute - for example, under
 514 BIB-1, if the attribute type is 1, then value 4 indictates a title
 515 search and 7 indictates an ISBN search; but if the attribute type is
 516 2, then value 4 indicates a ``greater than or equal'' search, and 102
 517 indicates a relevance match.
 518
 519 =back
 520
 521 =back
 522
 523 All of these classes except C<Attributes> and C<Attribute> are
 524 subclasses of the abstract class C<Net::Z3950::RPN::Node>.  That class
 525 has a single method, C<toPQF()>, which may be used to turn an RPN
 526 tree, or part of one, back into a textual prefix query.
 527
 528 Note that, apart to C<toPQF()>, none of these classes have any methods at
 529 all: the blessing into classes is largely just a documentation thing
 530 so that, for example, if you do
 531
 532         { use Data::Dumper; print Dumper($args->{RPN}) }
 533
 534 you get something fairly human-readable.  But of course, the type
 535 distinction between the three different kinds of boolean node is
 536 important.
 537
 538 By adding your own methods to these classes (building what I call
 539 ``augmented classes''), you can easily build code that walks the tree
 540 of the incoming RPN.  Take a look at C<samples/render-search.pl> for a
 541 sample implementation of such an augmented classes technique.
 542
 543
 544 =head2 Present handler
 545
 546 The presence of a present handler in a SimpleServer front-end is optional.
 547 Each time a client wishes to retrieve records, the present service is
 548 called. The present service allows the origin to request a certain number
 549 of records retrieved from a given result set.
 550 When the present handler is called, the front-end server should prepare a
 551 result set for fetching. In practice, this means to get access to the
 552 data from the backend database and store the data in a temporary fashion
 553 for fast and efficient fetching. The present handler does *not* fetch
 554 anything. This task is taken care of by the fetch handler, which will be
 555 called the correct number of times by the YAZ library. More about this
 556 below.
 557 If no present handler is implemented in the front-end, the YAZ toolkit
 558 will take care of a minimum of preparations itself. This default present
 559 handler is sufficient in many situations, where only a small amount of
 560 records are expected to be retrieved. If on the other hand, large result
 561 sets are likely to occur, the implementation of a reasonable present
 562 handler can gain performance significantly.
 563
 564 The informations exchanged between client and present handle are:
 565
 566   $args = {
 567                                     ## Client/server request:
 568
 569              GHANDLE   =>  $obj     ## Global handler specified at creation
 570              HANDLE    =>  ref,     ## Reference to datastructure
 571              SETNAME   =>  "id",    ## Result set ID
 572              START     =>  xxx,     ## Start position
 573              COMP      =>  "",      ## Desired record composition
 574              NUMBER    =>  yyy,     ## Number of requested records
 575
 576
 577                                     ## Respons parameters:
 578
 579              HITS      =>  zzz,     ## Number of returned records
 580              ERR_CODE  =>  0,       ## Error code
 581              ERR_STR   =>  ""       ## Error message
 582           };
 583
 584
 585 =head2 Fetch handler
 586
 587 The fetch handler is asked to retrieve a SINGLE record from a given
 588 result set (the front-end server will automatically call the fetch
 589 handler as many times as required).
 590
 591 The parameters exchanged between the server and the fetch handler are
 592
 593   $args = {
 594                                     ## Client/server request:
 595
 596              GHANDLE   =>  $obj     ## Global handler specified at creation
 597              HANDLE    =>  ref      ## Reference to data structure
 598              SETNAME   =>  "id"     ## ID of the requested result set
 599              OFFSET    =>  nnn      ## Record offset number
 600              REQ_FORM  =>  "n.m.k.l"## Client requested format OID
 601              COMP      =>  "xyz"    ## Formatting instructions
 602              SCHEMA    =>  "abc"    ## Requested schema, if any
 603
 604                                     ## Handler response:
 605
 606              RECORD    =>  ""       ## Record string
 607              BASENAME  =>  ""       ## Origin of returned record
 608              LAST      =>  0        ## Last record in set?
 609              ERR_CODE  =>  0        ## Error code
 610              ERR_STR   =>  ""       ## Error string
 611              SUR_FLAG  =>  0        ## Surrogate diagnostic flag
 612              REP_FORM  =>  "n.m.k.l"## Provided format OID
 613              SCHEMA    =>  "abc"    ## Provided schema, if any
 614           };
 615
 616 The REP_FORM value has by default the REQ_FORM value but can be set to
 617 something different if the handler desires. The BASENAME value should
 618 contain the name of the database from where the returned record originates.
 619 The ERR_CODE and ERR_STR works the same way they do in the search
 620 handler. If there is an error condition, the SUR_FLAG is used to
 621 indicate whether the error condition pertains to the record currently
 622 being retrieved, or whether it pertains to the operation as a whole
 623 (eg. the client has specified a result set which does not exist.)
 624
 625 If you need to return USMARC records, you might want to have a look at
 626 the MARC module on CPAN, if you don't already have a way of generating
 627 these.
 628
 629 NOTE: The record offset is 1-indexed - 1 is the offset of the first
 630 record in the set.
 631
 632 =head2 Scan handler
 633
 634 A full featured Z39.50 server should support scan (or in some literature
 635 browse). The client specifies a starting term of the scan, and the server
 636 should return an ordered list of specified length consisting of terms
 637 actually occurring in the data base. Each of these terms should be close
 638 to or equal to the term originally specified. The quality of scan compared
 639 to simple search is a guarantee of hits. It is simply like browsing through
 640 an index of a book, you always find something! The parameters exchanged are
 641
 642   $args = {
 643                                                 ## Client request
 644
 645                 GHANDLE         => $obj,        ## Global handler specified at creation
 646                 HANDLE          => $ref,        ## Reference to data structure
 647                 DATABASES       => ["xxx"],     ## Reference to a list of data-
 648                                                 ## bases to search
 649                 TERM            => 'start',     ## The start term
 650                 RPN             =>  $obj,       ## Reference to a Net::Z3950::RPN::Term
 651
 652                 NUMBER          => xx,          ## Number of requested terms
 653                 POS             => yy,          ## Position of starting point
 654                                                 ## within returned list
 655                 STEP            => 0,           ## Step size
 656
 657                                                 ## Server response
 658
 659                 ERR_CODE        => 0,           ## Error code
 660                 ERR_STR         => '',          ## Diagnostic message
 661                 NUMBER          => zz,          ## Number of returned terms
 662                 STATUS          => $status,     ## ScanSuccess/ScanFailure
 663                 ENTRIES         => $entries     ## Referenced list of terms
 664         };
 665
 666 where the term list is returned by reference in the scalar $entries, which
 667 should point at a data structure of this kind,
 668
 669   my $entries = [
 670                         {       TERM            => 'energy',
 671                                 OCCURRENCE      => 5            },
 672
 673                         {       TERM            => 'energy density',
 674                                 OCCURRENCE      => 6,           },
 675
 676                         {       TERM            => 'energy flow',
 677                                 OCCURRENCE      => 3            },
 678
 679                                 ...
 680
 681                                 ...
 682         ];
 683
 684 The $status flag is only meaningful after a successful scan, and
 685 should be assigned one of two values:
 686
 687   Net::Z3950::SimpleServer::ScanSuccess  Full success (default)
 688   Net::Z3950::SimpleServer::ScanPartial  Fewer terms returned than requested
 689
 690 The STEP member contains the requested number of entries in the term-list
 691 between two adjacent entries in the response.
 692
 693 A better alternative to the TERM member is the the RPN
 694 member, which is a reference to a Net::Z3950::RPN::Term object
 695 representing the scan cloause.  The structure of that object is the
 696 same as for Term objects included as part of the RPN tree passed to
 697 search handlers.  This is more useful than the simple TERM because it
 698 includes attributes (e.g. access points associated with the term),
 699 which are discarded by the TERM element.
 700
 701 =head2 Close handler
 702
 703 The argument hash recieved by the close handler has two elements only:
 704
 705   $args = {
 706                                     ## Server provides:
 707
 708              GHANDLE   =>  $obj     ## Global handler specified at creation
 709              HANDLE    =>  ref      ## Reference to data structure
 710           };
 711
 712 What ever data structure the HANDLE value points at goes out of scope
 713 after this call. If you need to close down a connection to your server
 714 or something similar, this is the place to do it.
 715
 716 =head2 Support for SRU and SRW
 717
 718 Since release 1.0, SimpleServer includes support for serving the SRU
 719 and SRW protocols as well as Z39.50.  These ``web-friendly'' protocols
 720 enable similar functionality to that of Z39.50, but by means of rich
 721 URLs in the case of SRU, and a SOAP-based web-service in the case of
 722 SRW.  These protocols are described at
 723 http://www.loc.gov/sru
 724
 725 In order to serve these protocols from a SimpleServer-based
 726 application, it is necessary to launch the application with a YAZ
 727 Generic Frontend Server (GFS) configuration file, which can be
 728 specified using the command-line argument C<-f> I<filename>.  A
 729 minimal configuration file looks like this:
 730
 731   <yazgfs>
 732     <server>
 733       <cql2rpn>pqf.properties</cql2rpn>
 734     </server>
 735   </yazgfs>
 736
 737 This file specifies only that C<pqf.properties> should be used to
 738 translate the CQL queries of SRU and SRW into corresponding Z39.50
 739 Type-1 queries.  For more information about YAZ GFS configuration,
 740 including how to specify an Explain record, see the I<Virtual Hosts>
 741 section of the YAZ manual at
 742 http://indexdata.com/yaz/doc/server.vhosts.tkl
 743
 744 The mapping of CQL queries into Z39.50 Type-1 queries is specified by
 745 a file that indicates which BIB-1 attributes should be generated for
 746 each CQL index, relation, modifiers, etc.  A typical section of this
 747 file looks like this:
 748
 749   index.dc.title                        = 1=4
 750   index.dc.subject                      = 1=21
 751   index.dc.creator                      = 1=1003
 752   relation.<                            = 2=1
 753   relation.le                           = 2=2
 754
 755 This file specifies the BIB-1 access points (type=1) for the Dublin
 756 Core indexes C<title>, C<subject> and C<creator>, and the BIB-1
 757 relations (type=2) corresponding to the CQL relations C<E<lt>> and
 758 C<E<lt>=>.  For more information about the format of this file, see
 759 the I<CQL> section of the YAZ manual at
 760 http://indexdata.com/yaz/doc/tools.tkl#tools.cql
 761
 762 The YAZ distribution include a sample CQL-to-PQF mapping configuration
 763 file called C<pqf.properties>; this is sufficient for many
 764 applications, and a good base to work from for most others.
 765
 766 If a SimpleServer-based application is run without this SRU-specific
 767 configuration, it can still serve SRU; however, CQL queries will not
 768 be translated, but passed straight through to the search-handler
 769 function, as the C<CQL> member of the parameters hash.  It is then the
 770 responsibility of the back-end application to parse and handle the CQL
 771 query, which is most easily done using Ed Summers' fine C<CQL::Parser>
 772 module, available from CPAN at
 773 http://search.cpan.org/~esummers/CQL-Parser/
 774
 775 =head1 AUTHORS
 776
 777 Anders Sønderberg (sondberg@indexdata.dk),
 778 Sebastian Hammer (quinn@indexdata.dk),
 779 Mike Taylor (indexdata.com).
 780
 781 =head1 SEE ALSO
 782
 783 Any Perl module which is useful for accessing the database of your
 784 choice.
 785
 786 =cut