X-Git-Url: http://git.indexdata.com/?p=simpleserver-moved-to-github.git;a=blobdiff_plain;f=SimpleServer.pm;h=540a04bc7fde928d8afccfe0032fb27ce2c302b7;hp=cc6c7d00081111116ad453d3e8e60000b3d7f1e9;hb=159d2f7d178c6870b07bb10fc8bcea009ad3e786;hpb=03aac9fd7958d065157b3c5878bf5a7c76420a0f diff --git a/SimpleServer.pm b/SimpleServer.pm index cc6c7d0..540a04b 100644 --- a/SimpleServer.pm +++ b/SimpleServer.pm @@ -26,7 +26,44 @@ ## ## $Log: SimpleServer.pm,v $ -## Revision 1.8 2001-08-29 10:29:51 sondberg +## 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 +## +## 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 +90,7 @@ require AutoLoader; @EXPORT = qw( ); -$VERSION = '0.02'; +$VERSION = '0.08'; bootstrap Net::Z3950::SimpleServer $VERSION; @@ -102,6 +139,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; @@ -234,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 }; @@ -249,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 @@ -271,6 +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, ## Reference to a Net::Z3950::APDU::Query ## Response parameters: @@ -315,6 +374,134 @@ 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. +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 is a hash with two fields: + +Z<> + +=over 4 + +=item C + +Optional. If present, it is a reference to a +C. This is a string of dot-separated integers +representing the OID of the query's top-level attribute set. + +=item C + +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 + +=item C + +=item C + +These three classes are all arrays of two elements, each of which is a +node of one of the above types. + +=item C + +See below for details. + +=back + +(I guess I should make a superclass C and make +all of these subclasses of it. Not done that yet, but will do soon.) + +=back + +=over 4 + +=item * + +C is a hash with two fields: + +Z<> + +=over 4 + +=item C + +A string containing the search term itself. + +=item C + +A reference to a C object. + +=back + +=item * + +C is an array of references to +C objects. (Note the plural/singular +distinction.) + +=item * + +C is a hash with three elements: + +Z<> + +=over 4 + +=item C + +Optional. If present, it is dot-separated OID string, as above. + +=item C + +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 + +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 for a +sample implementation of such an augmented classes technique. + + =head2 Present handler The presence of a present handler in a SimpleServer front-end is optional. @@ -424,7 +611,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 +632,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 +657,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 - -