X-Git-Url: http://lists.indexdata.com/cgi-bin?a=blobdiff_plain;f=doc%2Fserver.xml;h=4fa607b6d859480b0ed9745fbd588c66bf4254eb;hb=95bb55fadc3ff69e78e6a61b2096f1326979424b;hp=c39b4ab24453df92f499bf409c2af0619b7408c3;hpb=be1ed58119bbbc6063723f1a255ab67e18885d8f;p=idzebra-moved-to-github.git
diff --git a/doc/server.xml b/doc/server.xml
index c39b4ab..4fa607b 100644
--- a/doc/server.xml
+++ b/doc/server.xml
@@ -1,5 +1,5 @@
-
+
The Z39.50 Server
@@ -16,7 +16,7 @@
zebrasrv manpage -->
- DESCRIPTION
+ DescriptionZebra 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
@@ -36,12 +36,12 @@
- SYNOPSIS
+ Synopsis
&zebrasrv-synopsis;
- OPTIONS
+ Options
The options for zebrasrv are the same
@@ -52,19 +52,13 @@
&zebrasrv-options;
- VIRTUAL HOSTS
-
- zebrasrv uses the YAZ server frontend and does
- support multiple virtual servers behind multiple listening sockets.
-
- &zebrasrv-virtual;
-
- FILES
+
+ Fileszebra.cfg
- SEE ALSO
+ See Alsozebraidx
@@ -76,18 +70,6 @@
- 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 Datahttp://www.indexdata.dk
and distributed under the
@@ -497,8 +479,8 @@
-
-
+
+
Present
@@ -552,6 +534,132 @@
timeout.
+
+
+ Explain
+
+ Zebra maintains a "classic"
+ Explain database
+ on the side.
+ This database is called IR-Explain-1 and can be
+ searched using the attribute set exp-1.
+
+
+ The records in the explain database are of type
+ grs.sgml and can be retrieved as
+ SUTRS, XML,
+ GRS-1 and ASN.1 Explain.
+
+
+ Classic Explain only defines retrieaval of Explain information
+ via ASN.1. Pratically no Z39.50 clients supports this. Fortunately
+ they don't have to - since Zebra allows retrieval of this information
+ in the other formats.
+
+
+ The root element for the Explain grs.sgml records is
+ explain, thus
+ explain.abs is used for indexing.
+
+
+
+ Zebra must be able to locate
+ explain.abs in order to index the Explain
+ records properly. Zebra will work without it but the information
+ will not be searchable.
+
+
+
+ The following Explain categories are supported:
+ CategoryList, TargetInfo,
+ DatabaseInfo, AttributeDetails.
+
+
+ The following Explain search atributes are supported:
+ ExplainCategory (@attr 1=1),
+ DatabaseName (@attr 1=3),
+ DateAdded (@attr 1=9),
+ DateChanged(@ayyt 1=10).
+ See tab/explain.att for more information.
+
+
+
+ Example searches with yaz-client
+
+
+
+ List supported categories to find out which explain commands are
+ supported:
+
+ Z> base IR-Explain-1
+ Z> @attr exp1 1=1 categorylist
+ Z> form sutrs
+ Z> show 1+2
+
+
+
+
+ Get target info, that is, investigate which databases exist at
+ this server endpoint:
+
+ Z> base IR-Explain-1
+ Z> @attr exp1 1=1 targetinfo
+ Z> form xml
+ Z> show 1+1
+ Z> form grs-1
+ Z> show 1+1
+ Z> form sutrs
+ Z> show 1+1
+
+
+
+
+ List all supported databases, the number of hits
+ is the number of databases found, which most commonly are the
+ following two:
+ the Default and the
+ IR-Explain-1 databases.
+
+ Z> base IR-Explain-1
+ Z> f @attr exp1 1=1 databaseinfo
+ Z> form sutrs
+ Z> show 1+2
+
+
+
+
+ Get database info record for database Default.
+
+ Z> base IR-Explain-1
+ Z> @and @attr exp1 1=1 databaseinfo @attr exp1 1=3 Default
+
+ Identical query with explicitly specified attribute set:
+
+ Z> base IR-Explain-1
+ Z> @attrset exp1 @and @attr 1=1 databaseinfo @attr 1=3 Default
+
+
+
+
+ Get attribute details record for database
+ Default.
+ This query is very useful to study the internal Zebra indexes.
+ If records have been indexed using the alvis
+ XSLT filter, the string representation names of the known indexes can be
+ found.
+
+ Z> base IR-Explain-1
+ Z> @and @attr exp1 1=1 attributedetails @attr exp1 1=3 Default
+
+ Identical query with explicitly specified attribute set:
+
+ Z> base IR-Explain-1
+ Z> @attrset exp1 @and @attr 1=1 attributedetails @attr 1=3 Default
+
+
+
+
+
@@ -593,21 +701,26 @@
requests and handling them accordingly. This is a achieved through
the use of Deep Magic; civilians are warned not to stand too close.
+
+ From here on, ``SRU'' is used to indicate both the SRU and SRW
+ protocols, as they are identical except for the transport used for
+ the protocol packets and Zebra's support for them is equivalent.
+
- Running the SRU/SRW Server (zebrasrv)
+ Running the SRU 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
+ seem to follow that the SRU 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
+ will indeed recognise and accept SRU 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
+ It is possible to cheat, by having SRU search Zebra with
a PQF query instead of CQL, using the
x-pquery
parameter instead of
@@ -622,11 +735,11 @@
browser to:
- http://localhost:9999/Default?version=1.1&
- operation=searchRetrieve&
- x-pquery=mineral&
- startRecord=1&
- maximumRecords=1
+ 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
@@ -643,7 +756,7 @@
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
+ the salient point for SRU support is that
zebrasrv
must be started with the
-f frontendConfigFile
@@ -678,11 +791,204 @@
various CQL indexes, relations, etc. are translated into Type-1
queries.
+
+ A zebra server running with such a configuration can then be
+ queried using proper, conformant SRU URLs with CQL queries:
+
+
+ http://localhost:9999/Default?version=1.1
+ &operation=searchRetrieve
+ &query=title=utah and description=epicent*
+ &startRecord=1
+ &maximumRecords=1
+ SRU and SRW Protocol Support and Behavior
- ### x-pquery
+
+ Zebra running as an SRU server supports SRU version 1.1, including
+ CQL version 1.1. In particular, it provides support for the
+ following elements of the protocol.
+
+
+
+ Search and Retrieval
+
+ Zebra fully supports SRU's core
+ searchRetrieve
+ operation, as described at
+
+
+
+ One of the great strengths of SRU is that it mandates a standard
+ query language, CQL, and that all conforming implementations can
+ therefore be trusted to correctly interpret the same queries. It
+ is with some shame, then, that we admit that Zebra also supports
+ an additional query language, our own Prefix Query Format (PQF,
+ ).
+ A PQF query is submitted by using the extension parameter
+ x-pquery,
+ in which case the
+ query
+ parameter must be omitted, which makes the request not valid SRU.
+ Please don't do this.
+
+
+
+
+ Scan
+
+ Zebra does not support SRU's
+ scan
+ operation, as described at
+
+
+
+ This is a rather embarrassing surprise as the pieces are all
+ there: Z39.50 scan is supported, and SRU scan requests are
+ recognised and diagnosed. To add further to the embarrassment, a
+ mutant form of SRU scan is supported, using
+ the non-standard x-pScanClause parameter in
+ place of the standard scanClause to scan on a
+ PQF query clause.
+
+
+
+
+ Explain
+
+ Zebra fully supports SRU's core
+ explain
+ operation, as described at
+
+
+
+ The ZeeRex record explaining a database may be requested either
+ with a fully fledged SRU request (with
+ operation=explain
+ and version-number specified)
+ or with a simple HTTP GET at the server's basename.
+ The ZeeRex record returned in response is the one embedded
+ in the YAZ Frontend Server configuration file that is described in the
+ Virtual Hosts documentation.
+
+
+ Unfortunately, the data found in the
+ CQL-to-PQF text file must be added by hand-craft into the explain
+ section of the YAZ Frontend Server configuration file to be able
+ to provide a suitable explain record.
+ Too bad, but this is all extreme
+ new alpha stuff, and a lot of work has yet to be done ..
+
+
+ There is no linkeage whatsoever between the Z39.50 explain model
+ and the SRU/SRW explain response (well, at least not implemented
+ in Zebra, that is ..). Zebra does not provide a means using
+ Z39.50 to obtain the ZeeRex record.
+
+
+
+
+ Some SRU Examples
+
+ Surf into http://localhost:9999
+ to get an explain response, or use
+
+
+
+ See number of hits for a query
+
+
+
+ Fetch record 5-7 in Dublin Core format
+
+
+
+ Even search using PQF queries using the extended naughty
+ verbx-pquery
+
+
+
+ Or scan indexes using the extended extremely naughty
+ verbx-pScanClause
+
+ Don't do this in production code!
+ But it's a great fast debugging aid.
+
+
+
+
+ Initialization, Present, Sort, Close
+
+ In the Z39.50 protocol, Initialization, Present, Sort and Close
+ are separate operations. In SRU, however, these operations do not
+ exist.
+
+
+
+
+ SRU has no explicit initialization handshake phase, but
+ commences immediately with searching, scanning and explain
+ operations.
+
+
+
+
+ Neither does SRU have a close operation, since the protocol is
+ stateless and each request is self-contained. (It is true that
+ multiple SRU request/response pairs may be implemented as
+ multiple HTTP request/response pairs over a single persistent
+ TCP/IP connection; but the closure of that connection is not a
+ protocol-level operation.)
+
+
+
+
+ Retrieval in SRU is part of the
+ searchRetrieve operation, in which a search
+ is submitted and the response includes a subset of the records
+ in the result set. There is no direct analogue of Z39.50's
+ Present operation which requests records from an established
+ result set. In SRU, this is achieved by sending a subsequent
+ searchRetrieve request with the query
+ cql.resultSetId=id where
+ id is the identifier of the previously
+ generated result-set.
+
+
+
+
+ Sorting in CQL is done within the
+ searchRetrieve operation - in v1.1, by an
+ explicit sort parameter, but the forthcoming
+ v1.2 or v2.0 will most likely use an extension of the query
+ language, CQL for sorting: see
+
+
+
+
+
+ It can be seen, then, that while Zebra operating as an SRU server
+ does not provide the same set of operations as when operating as a
+ Z39.50 server, it does provide equivalent functionality.
+
+