From b05a82226d0840e32772c62285e9eab584ae000a Mon Sep 17 00:00:00 2001 From: Adam Dickmeiss Date: Thu, 8 Feb 2007 11:36:59 +0000 Subject: [PATCH] Fixed bug #615: Document retrievalInfo facilities for Frontend Server. --- NEWS | 2 + doc/gfs-virtual.xml | 13 ++- doc/tools.xml | 263 ++++++++++++++++++++++++++++++++++++++++++++++++- doc/yaz-ztest-man.xml | 17 +++- 4 files changed, 288 insertions(+), 7 deletions(-) diff --git a/NEWS b/NEWS index e710d9c..d8c0bd6 100644 --- a/NEWS +++ b/NEWS @@ -1,3 +1,5 @@ +Fixed bug #615: Document retrievalInfo facilities for Frontend Server. + Implemented pass-through CQL-to-PQF conversions. Bug #861. Fixed bug #832: Problem with MARC/charset in yaz-client. diff --git a/doc/gfs-virtual.xml b/doc/gfs-virtual.xml index 593e8bc..c866173 100644 --- a/doc/gfs-virtual.xml +++ b/doc/gfs-virtual.xml @@ -1,5 +1,5 @@ @@ -180,6 +180,17 @@ + + element retrievalinfo (optional) + + + Enables the retrieval facility supporting conversions and + specifications of record formats/types. + See for + more information. + + + diff --git a/doc/tools.xml b/doc/tools.xml index 9483a5c..6f565dc 100644 --- a/doc/tools.xml +++ b/doc/tools.xml @@ -1,4 +1,4 @@ - + Supporting Tools @@ -2147,6 +2147,267 @@ typedef struct oident + + Retrieval Facility + + YAZ version 2.1.20 or later includes a Retrieval facility tool + which allows a SRU/Z39.50 to describe itself and perform record + conversions. The idea is the following: + + + + + An SRU/Z39.50 client sends a retrieval request which includes + a combination of the following parameters: syntax (format), + schema (or element set name). + + + + + + The retrieval facility is invoked with parameters in a + server/proxy. The retrieval facility matches the parameters a set of + "supported" retrieval types. + If there is no match, the retrieval signals an error + (syntax and / or schema not supported). + + + + + + For a successful match, the backend is invoked with the same + or altered retrieval parameters (syntax, schema). If + a record is received from the backend, it is converted to the + frontend name / syntax. + + + + + + The resulting record is sent back the client and tagged with + the frontend syntax / schema. + + + + + + + The Retrieval facility is driven by an XML configuration. The + configuration is neither Z39.50 ZeeRex or SRU ZeeRex. But it + should be easy to generate both of them from the XML configuration. + (unfortunately the two versions + of ZeeRex differ substantially in this regard). + + + Retrieval XML format + + All elements should be covered by namespace + http://indexdata.com/yaz . + The root element node must be retrievalinfo. + + + The retrievalinfo must include one or + more retrieval elements. Each + retrieval defines specific combination of + syntax, name and identifier supported by this retrieval service. + + + The retrieval element may include any of the + following attributes: + + syntax (REQUIRED) + + + Defines the record syntax. Possible values is any + of the names defined in YAZ' OID database or a raw + OID in (n.n ... n). + + + + name (OPTIONAL) + + + Defines the name of the retrieval format. This can be + any string. For SRU, the value, is equivalent to schema (short-hand); + for Z39.50 it's equivalent to simple element set name. + + + + identifier (OPTIONAL) + + + Defines the URI schema name of the retrieval format. This can be + any string. For SRU, the value, is equivalent to URI schema. + For Z39.50, there is no equivalent. + + + + + + + The retrieval may include one + backend element. If a backend + element is given, it specifies how the records are retrieved by + some backend and how the records are converted from the backend to + the "frontend". + + + The attributes, name and syntax + may be specified for the backend element. These + semantics of these attributes is equivalent to those for the + retrieval. However, these values are passed to + the "backend". + + + The backend element may includes one or more + conversion instructions (as children elements). The supported + conversions are: + + marc + + + The marc element specifies a conversion + to - and from ISO2709 encoded MARC and + &marcxml;/MarcXchange. + The following attributes may be specified: + + + inputformat (REQUIRED) + + + Format of input. Supported values are + marc (for ISO2709); and xml + for MARCXML/MarcXchange. + + + + + outputformat (REQUIRED) + + + Format of output. Supported values are + line (MARC line format); + marcxml (for MARCXML), + marc (ISO2709), + marcxhcange (for MarcXchange). + + + + + inputcharset (OPTIONAL) + + + Encoding of input. For XML input formats, this need not + be given, but for ISO2709 based inputformats, this should + be set to the encoding used. For MARC21 records, a common + inputcharset value would be marc-8. + + + + + outputcharset (OPTIONAL) + + + Encoding of output. If outputformat is XML based, it is + strongly recommened to use utf-8. + + + + + + + + + xslt + + + The xslt element specifies a conversion + via &xslt;. The following attributes may be specified: + + + stylesheet (REQUIRED) + + + Stylesheet file. + + + + + + + + + + + + + Retrieval Facility Examples + + MARC21 backend + + A typical way to use the retrieval facility is to enable XML + for servers that only supports ISO2709 encoded MARC21 records. + + + + + + + + + + + + + + + + +]]> + + + This means that our frontend supports: + + + + MARC21 F(ull) records. + + + + + MARC21 B(rief) records. + + + + + + MARCXML records. + + + + + + Dublin core records. + + + + + + + + API + + It should be easy to use the retrieval systems from applications. Refer + to the headers + yaz/retrieval.h and + yaz/record_conv.h. + + + + YAZ @@ -69,7 +69,17 @@ yaz-<version>/include/yaz/backend.h - SEE ALSO + Retrieval Facility + + Refer to the "Retrieval Facility" in the YAZ manual + + + CQL to RPN conversions + + Refer to the "Specification of CQL to RPN mappings" in YAZ manual. + + + SEE ALSO yaz @@ -80,9 +90,6 @@ 7 - - Section "Generic server" in the YAZ manual. - -- 1.7.10.4