##
##
+## $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;
$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;
if (defined($self->{CLOSE})) {
set_close_handler($self->{CLOSE});
}
+ if (defined($self->{PRESENT})) {
+ set_present_handler($self->{PRESENT});
+ }
start_server(@args);
}
- Initialize request
- Search request
+ - Present request
- Fetching of records
- Closing down connection
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
$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
};
$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
};
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
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:
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
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.
projects / simpleserver-moved-to-github.git / blobdiff