Added simple README file, derived from POD comments in SimpleServer.pm

[simpleserver-moved-to-github.git] / SimpleServer.pm

diff --git a/SimpleServer.pm b/SimpleServer.pm
index cc6c7d0..d6546e7 100644 (file)
--- a/SimpleServer.pm
+++ b/SimpleServer.pm
@@ -26,7 +26,28 @@
 ##
 
 ## $Log: SimpleServer.pm,v $
-## Revision 1.8  2001-08-29 10:29:51  sondberg
+## Revision 1.13  2002-03-06 11:02:04  mike
+## Added simple README file, derived from POD comments in SimpleServer.pm
+## Fixed my (Mike Taylor's) email address
+##
+## Revision 1.12  2002/03/05 20:52:22  sondberg
+## Version 0.05 so that we can release the thing at CPAN.
+##
+## Revision 1.11  2002/03/05 20:49:56  sondberg
+## Added a couple of lines of documentation.
+##
+## Revision 1.10  2002/02/28 11:21:57  mike
+## Add RPN structure to search-handler argument hash.
+##
+## Revision 1.9  2001/08/29 11:48:36  sondberg
+## Added routines
+##
+##     Net::Z3950::SimpleServer::ScanSuccess
+##     Net::Z3950::SimpleServer::ScanPartial
+##
+## and a bit of documentation.
+##
+## 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
@@ -53,7 +74,7 @@ require AutoLoader;
 @EXPORT = qw(
        
 );
-$VERSION = '0.02';
+$VERSION = '0.05';
 
 bootstrap Net::Z3950::SimpleServer $VERSION;
 
@@ -102,6 +123,20 @@ sub launch_server {
 }
 
 
+# Register packages that we will use in translated RPNs
+package Net::Z3950::APDU::Query;
+package Net::Z3950::APDU::OID;
+package Net::Z3950::RPN::And;
+package Net::Z3950::RPN::Or;
+package Net::Z3950::RPN::AndNot;
+package Net::Z3950::RPN::Term;
+package Net::Z3950::RPN::Attributes;
+package Net::Z3950::RPN::Attribute;
+
+# Must revert to original package for Autoloader's benefit
+package Net::Z3950::SimpleServer;
+
+
 # Autoload methods go after =cut, and are processed by the autosplit program.
 
 1;
@@ -271,6 +306,8 @@ mous hash. The structure is the following:
             DATABASES =>  ["xxx"], ## Reference to a list of data-
                                    ## bases to search
             QUERY     =>  "query", ## The query expression
+            RPN       =>  $obj,    ## Blessed reference int the package
+                                   ## Net::Z3950::APDU::Query
 
                                    ## Response parameters:
 
@@ -315,6 +352,11 @@ it is perfectly legal to not accept boolean operators, but you SHOULD
 try to return good error codes if you run into something you can't or
 won't support.
 
+The RPN member is a blessed reference into the package Net::Z3950::APDU::Query.
+By means of an augmented type of coding, you can easily construct a
+parser of the incoming RPN. Take a look at samples/render-search.pl for
+a sample implementation of such an augmented parser technique. 
+
 =head2 Present handler
 
 The presence of a present handler in a SimpleServer front-end is optional.
@@ -424,7 +466,7 @@ an index of a book, you always find something! The parameters exchanged are
                ERR_CODE        => 0,           ## Error code
                ERR_STR         => '',          ## Diagnostic message
                NUMBER          => zz,          ## Number of returned terms
-               STATUS          => ScanSuccess, ## ScanSuccess/ScanFailure
+               STATUS          => $status,     ## ScanSuccess/ScanFailure
                ENTRIES         => $entries     ## Referenced list of terms
        };
 
@@ -445,7 +487,14 @@ should point at a data structure of this kind,
 
                                ...
        ];
-                       
+
+The $status flag should be assigned one of two values:
+
+  Net::Z3950::SimpleServer::ScanSuccess  On success (default)
+  Net::Z3950::SimpleServer::ScanPartial  Less terms returned than requested
+
+The STEP member contains the requested number of entries in the term-list
+between two adjacent entries in the response.
 
 =head2 Close handler
 
@@ -463,15 +512,12 @@ or something similar, this is the place to do it.
 =head1 AUTHORS
 
 Anders Sønderberg (sondberg@indexdata.dk) and Sebastian Hammer
-(quinn@indexdata.dk).
+(quinn@indexdata.dk). Substantial contributions made by Mike Taylor
+(mike@miketaylor.org.uk).
 
 =head1 SEE ALSO
 
-perl(1).
-
 Any Perl module which is useful for accessing the database of your
 choice.
 
 =cut
-
-