Added method Hash2grs into GRS1 module.

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

diff --git a/SimpleServer.pm b/SimpleServer.pm
index b2c27a1..523cf75 100644 (file)
--- 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;
 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->{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;
 
        bless $self, $class;
        return $self;

@@ -82,6 +88,9 @@ sub launch_server {
        if (defined($self->{CLOSE})) {
                set_close_handler($self->{CLOSE});
        }
        if (defined($self->{CLOSE})) {
                set_close_handler($self->{CLOSE});
        }

+       if (defined($self->{PRESENT})) {
+               set_present_handler($self->{PRESENT});
+       }

 
        start_server(@args);
 }
 
        start_server(@args);
 }

@@ -170,6 +179,7 @@ of events:
 
   - Initialize request
   - Search request
 
   - Initialize request
   - Search request

+  - Present request

   - Fetching of records
   - Closing down connection
 
   - 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,
                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
                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:
 
   $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
          };
 
             HANDLE    =>  undef    ## Handler of Perl data structure
          };
 

@@ -248,17 +259,17 @@ mous hash. The structure is the following:
   $args = {
                                    ## Request parameters:
 
   $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
                                    ## bases to search

-            QUERY     =>  "query"  ## The query expression
+            QUERY     =>  "query", ## The query expression

 
                                    ## Response parameters:
 
 
                                    ## 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
          };
 
             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.
 
 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
 =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
             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:
             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
             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
          };
 
 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.)
 
 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.
 
 NOTE: The record offset is 1-indexed - 1 is the offset of the first
 record in the set.