X-Git-Url: http://git.indexdata.com/?p=simpleserver-moved-to-github.git;a=blobdiff_plain;f=SimpleServer.pm;h=540a04bc7fde928d8afccfe0032fb27ce2c302b7;hp=d6546e73c726c0d7425d0e03a4d407ff156fbdda;hb=159d2f7d178c6870b07bb10fc8bcea009ad3e786;hpb=2a49c3688c23f4e1c3dcf23fc599ee3286df2811

diff --git a/SimpleServer.pm b/SimpleServer.pm
index d6546e7..540a04b 100644
--- a/SimpleServer.pm
+++ b/SimpleServer.pm
@@ -26,7 +26,23 @@
 ##
 
 ## $Log: SimpleServer.pm,v $
-## Revision 1.13  2002-03-06 11:02:04  mike
+## Revision 1.18  2003-09-09 20:12:38  mike
+## Return diagnostics on Init failure
+##
+## Revision 1.17  2003/09/09 11:40:10  mike
+## (Finally!) support implementation-ID
+##
+## Revision 1.16  2003/01/03 09:01:51  sondberg
+## Version 0.07.
+##
+## Revision 1.15  2002/09/16 14:00:16  sondberg
+## Updated Changes and added a few lines of documentation.
+##
+## Revision 1.14  2002/03/06 11:30:02  mike
+## Add RPN structure documentation to SimpleServer.pm's POD.
+## Add README to MANIFEST.
+##
+## 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
 ##
@@ -74,7 +90,7 @@ require AutoLoader;
 @EXPORT = qw(
 	
 );
-$VERSION = '0.05';
+$VERSION = '0.08';
 
 bootstrap Net::Z3950::SimpleServer $VERSION;
 
@@ -269,9 +285,15 @@ The argument hash passed to the init handler has the form
   $args = {
 				    ## Response parameters:
 
+	     IMP_ID    =>  "",      ## Z39.50 Implementation ID
 	     IMP_NAME  =>  "",      ## Z39.50 Implementation name
 	     IMP_VER   =>  "",      ## Z39.50 Implementation version
 	     ERR_CODE  =>  0,       ## Error code, cnf. Z39.50 manual
+	     ERR_STR   =>  "",      ## Error string (additional info.)
+	     USER      =>  "xxx"    ## If Z39.50 authentication is used,
+	     			    ## this member contains user name
+	     PASS      =>  "yyy"    ## Under same conditions, this member
+	     			    ## contains the password in clear text
 	     HANDLE    =>  undef    ## Handler of Perl data structure
 	  };
 
@@ -284,13 +306,14 @@ result sets or a handle to a back-end search engine of some sort),
 it is always best to store them in a private session structure -
 rather than leaving them in global variables in your script.
 
-The Implementation name and version are only really used by Z39.50
+The Implementation ID, name and version are only really used by Z39.50
 client developers to see what kind of server they're dealing with.
 Filling these in is optional.
 
 The ERR_CODE should be left at 0 (the default value) if you wish to
 accept the connection. Any other value is interpreted as a failure
-and the client will be shown the door.
+and the client will be shown the door, with the code and the
+associated additional information, ERR_STR returned.
 
 =head2 Search handler
 
@@ -306,8 +329,7 @@ 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
+	     RPN       =>  $obj,    ## Reference to a Net::Z3950::APDU::Query
 
 				    ## Response parameters:
 
@@ -352,10 +374,133 @@ 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. 
+A more convenient alternative to the QUERY member may be the RPN
+member, which is a reference to a Net::Z3950::APDU::Query object
+representing the RPN query tree.  The structure of that object is
+supposed to be self-documenting, but here's a brief summary of what
+you get:
+
+=over 4
+
+=item *
+
+C<Net::Z3950::APDU::Query> is a hash with two fields:
+
+Z<>
+
+=over 4
+
+=item C<attributeSet>
+
+Optional.  If present, it is a reference to a
+C<Net::Z3950::APDU::OID>.  This is a string of dot-separated integers
+representing the OID of the query's top-level attribute set.
+
+=item C<query>
+
+Mandatory: a refererence to the RPN tree itself.
+
+=back
+
+=item *
+
+Each node of the tree is an object of one of the following types:
+
+Z<>
+
+=over 4
+
+=item C<Net::Z3950::RPN::And>
+
+=item C<Net::Z3950::RPN::Or>
+
+=item C<Net::Z3950::RPN::AndNot>
+
+These three classes are all arrays of two elements, each of which is a
+node of one of the above types.
+
+=item C<Net::Z3950::RPN::Term>
+
+See below for details.
+
+=back
+
+(I guess I should make a superclass C<Net::Z3950::RPN::Node> and make
+all of these subclasses of it.  Not done that yet, but will do soon.)
+
+=back
+
+=over 4
+
+=item *
+
+C<Net::Z3950::RPN::Term> is a hash with two fields:
+
+Z<>
+
+=over 4
+
+=item C<term>
+
+A string containing the search term itself.
+
+=item C<attributes>
+
+A reference to a C<Net::Z3950::RPN::Attributes> object.
+
+=back
+
+=item *
+
+C<Net::Z3950::RPN::Attributes> is an array of references to
+C<Net::Z3950::RPN::Attribute> objects.  (Note the plural/singular
+distinction.)
+
+=item *
+
+C<Net::Z3950::RPN::Attribute> is a hash with three elements:
+
+Z<>
+
+=over 4
+
+=item C<attributeSet>
+
+Optional.  If present, it is dot-separated OID string, as above.
+
+=item C<attributeType>
+
+An integer indicating the type of the attribute - for example, under
+the BIB-1 attribute set, type 1 indicates a ``use'' attribute, type 2
+a ``relation'' attribute, etc.
+
+=item C<attributeValue>
+
+An integer indicating the value of the attribute - for example, under
+BIB-1, if the attribute type is 1, then value 4 indictates a title
+search and 7 indictates an ISBN search; but if the attribute type is
+2, then value 4 indicates a ``greater than or equal'' search, and 102
+indicates a relevance match.
+
+=back
+
+=back
+
+Note that, at the moment, none of these classes have any methods at
+all: the blessing into classes is largely just a documentation thing
+so that, for example, if you do
+
+	{ use Data::Dumper; print Dumper($args->{RPN}) }
+
+you get something fairly human-readable.  But of course, the type
+distinction between the three different kinds of boolean node is
+important.
+
+By adding your own methods to these classes (building what I call
+``augmented classes''), you can easily build code that walks the tree
+of the incoming RPN.  Take a look at C<samples/render-search.pl> for a
+sample implementation of such an augmented classes technique.
+
 
 =head2 Present handler