X-Git-Url: http://git.indexdata.com/?p=simpleserver-moved-to-github.git;a=blobdiff_plain;f=SimpleServer.pm;h=523cf751360b2bde2684bf62757d262cad4e7bb3;hp=b2c27a1ef7d75b817d1daae074fb69ed57e73c7b;hb=38818d8a4802abcbcfa58294ec0ddd166d9cc2ce;hpb=6755a668b35e7ddc4c7ac37fb2550a55fb9858ac diff --git a/SimpleServer.pm b/SimpleServer.pm index b2c27a1..523cf75 100644 --- a/SimpleServer.pm +++ b/SimpleServer.pm @@ -25,6 +25,11 @@ ## ## +## $Log: SimpleServer.pm,v $ +## Revision 1.6 2001-03-13 14:17:15 sondberg +## Added support for GRS-1. +## + package Net::Z3950::SimpleServer; use strict; @@ -64,6 +69,7 @@ sub new { $self->{SEARCH} = $args->{SEARCH} || croak "SimpleServer.pm: ERROR: Unspecified search handler"; $self->{FETCH} = $args->{FETCH} || croak "SimpleServer.pm: ERROR: Unspecified fetch handler"; $self->{CLOSE} = $args->{CLOSE}; + $self->{PRESENT} = $args->{PRESENT}; bless $self, $class; return $self; @@ -82,6 +88,9 @@ sub launch_server { if (defined($self->{CLOSE})) { set_close_handler($self->{CLOSE}); } + if (defined($self->{PRESENT})) { + set_present_handler($self->{PRESENT}); + } start_server(@args); } @@ -170,6 +179,7 @@ of events: - Initialize request - Search request + - Present request - Fetching of records - Closing down connection @@ -191,6 +201,7 @@ means of the the SimpleServer object constructor INIT => \&my_init_handler, CLOSE => \&my_close_handler, SEARCH => \&my_search_handler, + PRESENT => \&my_present_handler, FETCH => \&my_fetch_handler }); After the custom event handles are declared, the server is launched @@ -217,9 +228,9 @@ The argument hash passed to the init handler has the form $args = { ## Response parameters: - IMP_NAME => "" ## Z39.50 Implementation name - IMP_VER => "" ## Z39.50 Implementation version - ERR_CODE => 0 ## Error code, cnf. Z39.50 manual + IMP_NAME => "", ## Z39.50 Implementation name + IMP_VER => "", ## Z39.50 Implementation version + ERR_CODE => 0, ## Error code, cnf. Z39.50 manual HANDLE => undef ## Handler of Perl data structure }; @@ -248,17 +259,17 @@ mous hash. The structure is the following: $args = { ## Request parameters: - HANDLE => ref ## Your session reference. - SETNAME => "id" ## ID of the result set - REPL_SET => 0 ## Replace set if already existing? - DATABASES => ["xxx"] ## Reference to a list of data- + HANDLE => ref, ## Your session reference. + SETNAME => "id", ## ID of the result set + REPL_SET => 0, ## Replace set if already existing? + DATABASES => ["xxx"], ## Reference to a list of data- ## bases to search - QUERY => "query" ## The query expression + QUERY => "query", ## The query expression ## Response parameters: - ERR_CODE => 0 ## Error code (0=Succesful search) - ERR_STR => "" ## Error string + ERR_CODE => 0, ## Error code (0=Succesful search) + ERR_STR => "", ## Error string HITS => 0 ## Number of matches }; @@ -298,6 +309,46 @@ 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. +=head2 Present handler + +The presence of a present handler in a SimpleServer front-end is optional. +Each time a client wishes to retrieve records, the present service is +called. The present service allows the origin to request a certain number +of records retrieved from a given result set. +When the present handler is called, the front-end server should prepare a +result set for fetching. In practice, this means to get access to the +data from the backend database and store the data in a temporary fashion +for fast and efficient fetching. The present handler does *not* fetch +anything. This task is taken care of by the fetch handler, which will be +called the correct number of times by the YAZ library. More about this +below. +If no present handler is implemented in the front-end, the YAZ toolkit +will take care of a minimum of preparations itself. This default present +handler is sufficient in many situations, where only a small amount of +records are expected to be retrieved. If on the other hand, large result +sets are likely to occur, the implementation of a reasonable present +handler can gain performance significantly. + +The informations exchanged between client and present handle are: + + $args = { + ## Client/server request: + + HANDLE => ref, ## Reference to datastructure + SETNAME => "id", ## Result set ID + START => xxx, ## Start position + COMP => "", ## Desired record composition + NUMBER => yyy, ## Number of requested records + + + ## Respons parameters: + + HITS => zzz, ## Number of returned records + ERR_CODE => 0, ## Error code + ERR_STR => "" ## Error message + }; + + =head2 Fetch handler The fetch handler is asked to retrieve a SINGLE record from a given @@ -312,7 +363,7 @@ The parameters exchanged between the server and the fetch handler are HANDLE => ref ## Reference to data structure SETNAME => "id" ## ID of the requested result set OFFSET => nnn ## Record offset number - REQ_FORM => "USMARC" ## Client requested record format + REQ_FORM => "n.m.k.l"## Client requested format OID COMP => "xyz" ## Formatting instructions ## Handler response: @@ -323,7 +374,7 @@ The parameters exchanged between the server and the fetch handler are ERR_CODE => 0 ## Error code ERR_STR => "" ## Error string SUR_FLAG => 0 ## Surrogate diagnostic flag - REP_FORM => "USMARC" ## Provided record format + REP_FORM => "n.m.k.l"## Provided format OID }; The REP_FORM value has by default the REQ_FORM value but can be set to @@ -335,12 +386,9 @@ indicate whether the error condition pertains to the record currently being retrieved, or whether it pertains to the operation as a whole (eg. the client has specified a result set which does not exist.) -Record formats are currently carried as strings (eg. USMARC, TEXT_XML, -SUTRS), but this will probably change to proper OID strings in the -future (not to worry, though, the module will supply constant values -for the common OIDs). If you need to return USMARC records, you might -want to have a look at the MARC module on CPAN, if you don't already -have a way of generating these. +If you need to return USMARC records, you might want to have a look at +the MARC module on CPAN, if you don't already have a way of generating +these. NOTE: The record offset is 1-indexed - 1 is the offset of the first record in the set.