From 03aac9fd7958d065157b3c5878bf5a7c76420a0f Mon Sep 17 00:00:00 2001 From: "Anders S. Mortensen" Date: Wed, 29 Aug 2001 10:29:51 +0000 Subject: [PATCH] Added some documentation of scan. --- SimpleServer.pm | 79 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 65 insertions(+), 14 deletions(-) diff --git a/SimpleServer.pm b/SimpleServer.pm index a7bb235..cc6c7d0 100644 --- a/SimpleServer.pm +++ b/SimpleServer.pm @@ -26,7 +26,10 @@ ## ## $Log: SimpleServer.pm,v $ -## Revision 1.7 2001-08-24 14:00:20 sondberg +## Revision 1.8 2001-08-29 10:29:51 sondberg +## Added some documentation of scan. +## +## Revision 1.7 2001/08/24 14:00:20 sondberg ## Added support for scan. ## ## Revision 1.6 2001/03/13 14:17:15 sondberg @@ -131,7 +134,7 @@ Net::Z3950::SimpleServer - Simple Perl API for building Z39.50 servers. my $set_id = $args->{SETNAME}; - my $record = fetch_a_record($args->{OFFSET); + my $record = fetch_a_record($args->{OFFSET}); $args->{RECORD} = $record; if (number_of_hits() == $args->{OFFSET}) { ## Last record in set? @@ -144,15 +147,13 @@ Net::Z3950::SimpleServer - Simple Perl API for building Z39.50 servers. ## Register custom event handlers: - my $handle = Net::Z3950::SimpleServer->new({ - INIT => \&my_init_handler, + my $z = new Net::Z3950::SimpleServer( INIT => \&my_init_handler, CLOSE => \&my_close_handler, SEARCH => \&my_search_handler, - FETCH => \&my_fetch_handler - }); + FETCH => \&my_fetch_handler); ## Launch server: - $handle->launch_server("ztest.pl", @ARGV); + $z->launch_server("ztest.pl", @ARGV); =head1 DESCRIPTION @@ -184,6 +185,7 @@ of events: - Search request - Present request - Fetching of records + - Scan request (browsing) - Closing down connection Note that only the Search and Fetch handler functions are required. @@ -200,17 +202,18 @@ output parameters. The Perl programmer specifies the event handles for the server by means of the the SimpleServer object constructor - my $handle = Net::Z3950::SimpleServer->new({ - INIT => \&my_init_handler, - CLOSE => \&my_close_handler, - SEARCH => \&my_search_handler, - PRESENT => \&my_present_handler, - FETCH => \&my_fetch_handler }); + my $z = new Net::Z3950::SimpleServer( + INIT => \&my_init_handler, + CLOSE => \&my_close_handler, + SEARCH => \&my_search_handler, + PRESENT => \&my_present_handler, + SCAN => \&my_scan_handler, + FETCH => \&my_fetch_handler); After the custom event handles are declared, the server is launched by means of the method - $handle->launch_server("MyServer.pl", @ARGV); + $z->launch_server("MyServer.pl", @ARGV); Notice, the first argument should be the name of your server script (for logging purposes), while the rest of the arguments @@ -396,6 +399,54 @@ these. NOTE: The record offset is 1-indexed - 1 is the offset of the first record in the set. +=head2 Scan handler + +A full featured Z39.50 server should support scan (or in some literature +browse). The client specifies a starting term of the scan, and the server +should return an ordered list of specified length consisting of terms +actually occurring in the data base. Each of these terms should be close +to or equal to the term originally specified. The quality of scan compared +to simple search is a guarantee of hits. It is simply like browsing through +an index of a book, you always find something! The parameters exchanged are + + $args = { + ## Client request + + HANDLE => $ref ## Reference to data structure + TERM => 'start', ## The start term + NUMBER => xx, ## Number of requested terms + POS => yy, ## Position of starting point + ## within returned list + STEP => 0, ## Step size + + ## Server response + + ERR_CODE => 0, ## Error code + ERR_STR => '', ## Diagnostic message + NUMBER => zz, ## Number of returned terms + STATUS => ScanSuccess, ## ScanSuccess/ScanFailure + ENTRIES => $entries ## Referenced list of terms + }; + +where the term list is returned by reference in the scalar $entries, which +should point at a data structure of this kind, + + my $entries = [ + { TERM => 'energy', + OCCURRENCE => 5 }, + + { TERM => 'energy density', + OCCURRENCE => 6, }, + + { TERM => 'energy flow', + OCCURRENCE => 3 }, + + ... + + ... + ]; + + =head2 Close handler The argument hash recieved by the close handler has one element only: -- 1.7.10.4