X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Ffrontend.xml;h=985f4bd18348a9985b74ea7db56e3f8b4afcef5a;hp=dbd210475e456ca992fe589b03318cd5f5036921;hb=95d8bd04e10519a635972a24176270ef4dbe8d2c;hpb=b7e415906df8d63b3607c892dc2f6ef6bbea8fb1 diff --git a/doc/frontend.xml b/doc/frontend.xml index dbd2104..985f4bd 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 or SRW, &yaz; basically offers your two options. You + means of Z39.50, SRW o SRU, &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. @@ -44,8 +44,7 @@ - The &yaz; server does not provide full SRW functionality. - However, it provides an adapter for SRW (to Z39.50). + The &yaz; server does not support XCQL. @@ -100,6 +99,10 @@ Result-Set Sort (optional). + + Return Explain for SRW/SRU (optional). + + @@ -233,7 +236,7 @@ statserv_options_block *statserv_getcontrol(void); int idle_timeout; Maximum session idle-time, in minutes. Zero indicates - no (infinite) timeout. Default is 120 minutes. + no (infinite) timeout. Default is 15 minutes. @@ -333,8 +336,8 @@ bend_initresult (*bend_init)(bend_initrequest *r); - This handler is also called when operating in SRW mode - when - a connection has been made (even though SRW does not offer + 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). @@ -373,6 +376,8 @@ typedef struct bend_initrequest /* character set and language negotiation - see include/yaz/z-charneg.h */ Z_CharSetandLanguageNegotiation *charneg_request; Z_External *charneg_response; + int (*bend_srw_explain)(void *handle, bend_explain_rr *rr); + int (*bend_srw_scan)(void *handle, bend_scan_rr *rr); } bend_initrequest; typedef struct bend_initresult @@ -459,6 +464,7 @@ typedef struct { int hits; /* number of hits */ int errcode; /* 0==OK */ char *errstring; /* system error string or NULL */ + Z_OtherInformation *search_info; } bend_search_rr; @@ -497,8 +503,8 @@ typedef struct { The bend_search handler is also called when - the frontend server receives a SRW SearchRetrieveRequest. - For SRW, a CQL query is usually provided by the client. + 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, @@ -509,8 +515,8 @@ typedef struct { To maintain backwards compatibility, the frontend server of yaz always assume that error codes are BIB-1 diagnostics. - For SRW operation, a Bib-1 diagnostic code is mapped to - SRW diagnostic. + For SRW/SRU operation, a Bib-1 diagnostic code is mapped to + SRW/SRU diagnostic. @@ -535,21 +541,22 @@ 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 Z39.50 Search Request, a - Z39.50 Present Request or a SRW SearchRetrieveRequest. + 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 being the first record in the set). The format field - is the record format requested by the client (See section - Object Identifiers). The value - VAL_NONE indicates that the client did not - request a specific format. The stream argument + is the record format requested by the client (See + ). + The value VAL_NONE indicates that the client did + not request a specific format. The stream argument is an &odr; stream which should be used for allocating space for structured data records. The stream will be reset when all records have been assembled, and @@ -559,13 +566,13 @@ typedef struct bend_fetch_rr { - If a SRW SearchRetrieveRequest is received by the frontend server, - the referenceId is NULL, the request_format - (transfer syntax) is XML (OID name + 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 is stored in the + The schema for SRW/SRU is stored in both the Z_RecordComposition - structure. + structure and schema (simple string). @@ -573,7 +580,7 @@ typedef struct bend_fetch_rr { 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 @@ -715,8 +722,22 @@ typedef struct bend_scan_rr { bend_scan_status status; int errcode; char *errstring; + char *scanClause; /* CQL scan clause */ } bend_scan_rr; + + This backend server handles both Z39.50 scan + and SRW/SRU scan. In order for a + handler to distinguish between SRW/SRU (CQL) scan + Z39.50 Scan , it must check for a non-NULL value of + scanClause. + + + + if designed today, it would be a choice using a union or similar, + but that would break binary compatibility with existing servers. + + @@ -726,27 +747,13 @@ typedef struct bend_scan_rr { The finished application has the following invocation syntax (by way of statserv_main()): - - - appname - - - - - - - - - - - - listener-spec - + + &gfs-synopsis; The options are: - &ztest-options; + &gfs-options; @@ -764,7 +771,7 @@ typedef struct bend_scan_rr { hostname | IP-number [: portnumber] - + The port number defaults to 210 (standard Z39.50 port). @@ -774,22 +781,62 @@ typedef struct bend_scan_rr { - 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:@:210 - - ssl:@:3000 - - unix:/tmp/yaz - + For TCP/IP and SSL, the special hostname @ + (at sign) is mapped to the address INADDR_ANY, + which causes the server to listen on any local interface. + Running the GFS on Unix + + Assuming the server application appname is + started as root, the following will make it listen on port 210. + The server will change identity to nobody + and write its log to /var/log/app.log. + + appname -l /var/log/app.log -u nobody tcp:@:210 + + + + The server will accept Z39.50 requests and offer SRW/SRU service + on port 210. + + + Setting up Apache as SRW/SRU Frontend + + If you use Apache + as your public web server and want to offer HTTP port 80 + access to the YAZ server on 210, you can use the + + ProxyPass + directive. + If you have virtual host + srw.mydomain you can use the following directives + in Apache's httpd.conf: + + <VirtualHost *> + ErrorLog /home/srw/logs/error_log + TransferLog /home/srw/logs/access_log + ProxyPass / http://srw.mydomain:210/ + </VirtualHost> + + + + The above for the Apache 1.3 series. + + + Running a server with local access only + + Servers that is only being accessed from the local host should listen + on UNIX file socket rather than a Internet socket. To listen on + /tmp/mysocket start the server as follows: + + appname tcp:/tmp/mysocket + + + + + Virtual Hosts + &gfs-virtual;