X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fserver.xml;h=c39b4ab24453df92f499bf409c2af0619b7408c3;hb=be1ed58119bbbc6063723f1a255ab67e18885d8f;hp=8066c45425a1b03fa771a6403f99c1bc19391acd;hpb=4fe772289b1ab968655c27b144d08fc69c113fd9;p=idzebra-moved-to-github.git diff --git a/doc/server.xml b/doc/server.xml index 8066c45..c39b4ab 100644 --- a/doc/server.xml +++ b/doc/server.xml @@ -1,22 +1,106 @@ - + The Z39.50 Server Running the Z39.50 Server (zebrasrv) - + + + + + DESCRIPTION + Zebra is a high-performance, general-purpose structured text indexing + and retrieval engine. It reads structured records in a variety of input + formats (eg. email, XML, MARC) and allows access to them through exact + boolean search expressions and relevance-ranked free-text queries. + + + zebrasrv is the Z39.50 and SRW/U frontend + server for the Zebra indexer. + + + On Unix you can run the zebrasrv + server from the command line - and put it + in the background. It may also operate under the inet daemon. + On WIN32 you can run the server as a console application or + as a WIN32 Service. + + + + + SYNOPSIS + &zebrasrv-synopsis; + + + + OPTIONS + + + The options for zebrasrv are the same + as those for YAZ' yaz-ztest. + Option -c specifies a Zebra configuration + file - if omitted zebra.cfg is read. + + + &zebrasrv-options; + + VIRTUAL HOSTS + + zebrasrv uses the YAZ server frontend and does + support multiple virtual servers behind multiple listening sockets. + + &zebrasrv-virtual; + + FILES + + zebra.cfg + + + SEE ALSO + + + zebraidx + 1 + , + + yaz-ztest + 8 + + + + Section "The Z39.50 Server" in the Zebra manual. + http://www.indexdata.dk/zebra/doc/server.tkl + + + Section "Virtual Hosts" in the YAZ manual. + http://www.indexdata.dk/yaz/doc/server.vhosts.tkl + + + Section "Specification of CQL to RPN mappings" in the YAZ manual. + http://www.indexdata.dk/yaz/doc/tools.tkl#tools.cql.map + + + The Zebra software is Copyright Index Data + http://www.indexdata.dk + and distributed under the + GPLv2 license. + + + + + Z39.50 Protocol Support and Behavior @@ -218,11 +239,11 @@ Search - + The supported query type are 1 and 101. All operators are currently @@ -235,7 +256,7 @@ - The server has full support for piggy-backed present requests (see + The server has full support for piggy-backed retrieval (see also the following section). @@ -258,6 +279,7 @@ A phrase register is created for those fields in the .abs file that contains a p-specifier. + @@ -321,7 +343,7 @@ For the Truncation attribute, No Truncation is the default. Left Truncation is not supported. - Process # is supported, as is + Process # in search term is supported, as is Regxp-1. Regxp-2 enables the fault-tolerant (fuzzy) search. As a default, a single error (deletion, insertion, @@ -388,8 +410,7 @@ x? - Matches x once or twice. Priority: high. - FIXME Is this right? Std regexp has '?' meaning zero or one -H + Matches x zero or once. Priority: high. @@ -403,7 +424,7 @@ - x|y + x|y Matches either x or y. @@ -533,6 +554,138 @@ + + + + The SRU/SRW Server + + In addition to Z39.50, Zebra supports the more recent and + web-friendly IR protocol SRU, described at + . + SRU is ``Search/Retrieve via URL'', a simple, REST-like protocol + that uses HTTP GET to request search responses. The request + itself is made of parameters such as + query, + startRecord, + maximumRecords + and + recordSchema; + the response is an XML document containing hit-count, result-set + records, diagnostics, etc. SRU can be thought of as a re-casting + of Z39.50 semantics in web-friendly terms; or as a standardisation + of the ad-hoc query parameters used by search engines such as Google + and AltaVista; or as a superset of A9's OpenSearch (which it + predates). + + + Zebra further supports SRW, described at + . + SRW is the ``Search/Retrieve Web Service'', a SOAP-based alternative + implementation of the abstract protocol that SRU implements as HTTP + GET requests. In SRW, requests are encoded as XML documents which + are posted to the server. The responses are identical to those + returned by SRU servers, except that they are wrapped in a several + layers of SOAP envelope. + + + Zebra supports all three protocols - Z39.50, SRU and SRW - on the + same port, recognising what protocol is used by each incoming + requests and handling them accordingly. This is a achieved through + the use of Deep Magic; civilians are warned not to stand too close. + + + + Running the SRU/SRW Server (zebrasrv) + + Because Zebra supports all three protocols on one port, it would + seem to follow that the SRU/SRW server is run in the same way as + the Z39.50 server, as described above. This is true, but only in + an uninterestingly vacuous way: a Zebra server run in this manner + will indeed recognise and accept SRU and SRW requests; but since it + doesn't know how to handle the CQL queries that these protocols + use, all it can do is send failure responses. + + + + It is possible to cheat, by having SRU or SRW search Zebra with + a PQF query instead of CQL, using the + x-pquery + parameter instead of + query. + This is a + non-standard extension + of CQL, and a + very naughty + thing to do, but it does give you a way to see Zebra serving SRU + ``right out of the box''. If you start your favourite Zebra + server in the usual way, on port 9999, then you can send your web + browser to: + + + http://localhost:9999/Default?version=1.1& + operation=searchRetrieve& + x-pquery=mineral& + startRecord=1& + maximumRecords=1 + + + This will display the XML-formatted SRU response that includes the + first record in the result-set found by the query + mineral. (For clarity, the SRU URL is shown + here broken across lines, but the lines should be joined to gether + to make single-line URL for the browser to submit.) + + + + In order to turn on Zebra's support for CQL queries, it's necessary + to have the YAZ generic front-end (which Zebra uses) translate them + into the Z39.50 Type-1 query format that is used internally. And + to do this, the generic front-end's own configuration file must be + used. This file is described + elsewhere; + the salient point for SRU and SRW support is that + zebrasrv + must be started with the + -f frontendConfigFile + option rather than the + -c zebraConfigFile + option, + and that the front-end configuration file must include both a + reference to the Zebra configuration file and the CQL-to-PQF + translator configuration file. + + + A minimal front-end configuration file that does this would read as + follows: + + + + zebra.cfg + ../../tab/pqf.properties + + +]]> + + The + <config> + element contains the name of the Zebra configuration file that was + previously specified by the + -c + command-line argument, and the + <cql2rpn> + element contains the name of the CQL properties file specifying how + various CQL indexes, relations, etc. are translated into Type-1 + queries. + + + + + SRU and SRW Protocol Support and Behavior + ### x-pquery + + +