X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Ffrontend.xml;h=cbb533ac2e7c02f615ff3ba68c753978b63302c4;hb=a54c709b3e2feff5762bfa7dfa8ee653b429d369;hp=65d21fc58aa7413d2d8d559505de404c31d06253;hpb=94fce64abe00f0334941ca270c8898bdabb0ca7c;p=yaz-moved-to-github.git diff --git a/doc/frontend.xml b/doc/frontend.xml index 65d21fc..cbb533a 100644 --- a/doc/frontend.xml +++ b/doc/frontend.xml @@ -1,4 +1,4 @@ - + Generic server Introduction @@ -13,7 +13,7 @@ If you have a database system that you would like to make available by - means of Z39.50, &yaz; basically offers your two options. You + means of Z39.50 or SRW, &yaz; basically offers your two options. You can use the APIs provided by the &asn;, &odr;, and &comstack; modules to create and decode PDUs, and exchange them with a client. @@ -41,6 +41,12 @@ too many structural changes in existing applications. + + + + The &yaz; server does not support XCQL. + + The Database Frontend @@ -324,6 +330,13 @@ bend_initresult (*bend_init)(bend_initrequest *r); bend_init handler is passed in the call to statserv_start. + + + This handler is also called when operating in SRW/SRU mode - when + a connection has been made (even though SRW/SRU does not offer + this service). + + Unlike previous versions of YAZ, the bend_init also serves as a handler that defines the Z39.50 services that the backend @@ -354,6 +367,11 @@ typedef struct bend_initrequest int (*bend_delete)(void *handle, bend_delete_rr *rr); int (*bend_scan)(void *handle, bend_scan_rr *rr); int (*bend_segment)(void *handle, bend_segment_rr *rr); + + ODR decode; /* decoding stream */ + /* character set and language negotiation - see include/yaz/z-charneg.h */ + Z_CharSetandLanguageNegotiation *charneg_request; + Z_External *charneg_response; } bend_initrequest; typedef struct bend_initresult @@ -441,12 +459,11 @@ typedef struct { int errcode; /* 0==OK */ char *errstring; /* system error string or NULL */ } bend_search_rr; - The bend_search handler is a fairly close - approximation of a protocol Search Request - and Response PDUs + approximation of a protocol Z39.50 Search Request - and Response PDUs The setname is the resultSetName from the protocol. You are required to establish a mapping between the set name and whatever your backend database likes to use. @@ -477,7 +494,24 @@ typedef struct { defined error codes, and the suggested uses of the addinfo field. + + The bend_search handler is also called when + the frontend server receives a SRW/SRU SearchRetrieveRequest. + For SRW/SRU, a CQL query is usually provided by the client. + The CQL query is available as part of Z_Query + structure (note that CQL is now part of Z39.50 via an external). + To support CQL in existing implementations that only do Type-1, + we refer to the CQL-to-PQF tool described + here. + + + To maintain backwards compatibility, the frontend server + of yaz always assume that error codes are BIB-1 diagnostics. + For SRW/SRU operation, a Bib-1 diagnostic code is mapped to + SRW/SRU diagnostic. + + int (*bend_fetch) (void *handle, bend_fetch_rr *rr); @@ -500,13 +534,14 @@ typedef struct bend_fetch_rr { int errcode; /* 0==success */ char *errstring; /* system error string or NULL */ int surrogate_flag; /* surrogate diagnostic */ + char *schema; /* string record schema input/output */ } bend_fetch_rr; The frontend server calls the bend_fetch handler - when it needs database records to fulfill a Search Request or a Present - Request. + when it needs database records to fulfill a Z39.50 Search Request, a + Z39.50 Present Request or a SRW SearchRetrieveRequest. The setname is simply the name of the result set that holds the reference to the desired record. The number is the offset into the set (with 1 @@ -524,11 +559,21 @@ typedef struct bend_fetch_rr { + If a SRW/SRU SearchRetrieveRequest is received by the frontend server, + the referenceId is NULL and the + request_format (transfer syntax) is XML (OID name + VAL_TEXT_XML). + The schema for SRW/SRU is stored in both the + Z_RecordComposition + structure and schema (simple string). + + + In the structure, the basename is the name of the database that holds the record. len is the length of the record returned, in bytes, and record is a pointer to the record. - Last_in_set should be nonzero only if the record + last_in_set should be nonzero only if the record returned is the last one in the given result set. errcode and errstring, if given, will be interpreted as a global error pertaining to the @@ -588,7 +633,8 @@ typedef struct { The bend_present handler is called when - the server receives a Present Request. The setname, + the server receives a Z39.50 Present Request. + The setname, start and number is the name of the result set - start position - and number of records to be retrieved respectively. format and @@ -692,8 +738,8 @@ typedef struct bend_scan_rr { - + listener-spec @@ -726,23 +772,22 @@ typedef struct bend_scan_rr { For UNIX, the address is the filename of socket. - + - Examples + For TCP/IP and SSL, the special hostname "@" is mapped to + the address INADDR_ANY, which causes the + server to listen on any local interface. - + + + Examples: - tcp:dranet.dra.com + tcp:@:210 - ssl:ssl.enterprise.com:3000 + ssl:@:3000 unix:/tmp/yaz - - - For TCP/IP and SSL, the special hostname "@" is mapped to - the address INADDR_ANY, which causes the - server to listen on any local interface.