dependencies/yaz_3.0.14/doc/tools.retrieval.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>6. Retrieval Facility</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"><link rel="start" href="index.html" title="YAZ User's Guide and Reference"><link rel="up" href="tools.html" title="Chapter 9. Supporting Tools"><link rel="prev" href="marc.html" title="5. MARC"><link rel="next" href="odr.html" title="Chapter 10. The ODR Module"></head><body><link rel="stylesheet" type="text/css" href="common/style1.css"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">6. Retrieval Facility</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="marc.html">Prev</a> </td><th width="60%" align="center">Chapter 9. Supporting Tools</th><td width="20%" align="right"> <a accesskey="n" href="odr.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tools.retrieval"></a>6. Retrieval Facility</h2></div></div></div><p>
   2     YAZ version 2.1.20 or later includes a Retrieval facility tool
   3     which allows a SRU/Z39.50 to describe itself and perform record
   4     conversions. The idea is the following:
   5
   6     </p><div class="itemizedlist"><ul type="disc"><li><p>
   7        An SRU/Z39.50 client sends a retrieval request which includes
   8        a combination of the following parameters: syntax (format),
   9        schema (or element set name).
  10       </p></li><li><p>
  11        The retrieval facility is invoked with parameters in a
  12        server/proxy. The retrieval facility matches the parameters a set of
  13        "supported" retrieval types.
  14        If there is no match, the retrieval signals an error
  15        (syntax and / or schema not supported).
  16       </p></li><li><p>
  17        For a successful match, the backend is invoked with the same
  18        or altered retrieval parameters (syntax, schema). If
  19        a record is received from the backend, it is converted to the
  20        frontend name / syntax.
  21       </p></li><li><p>
  22        The resulting record is sent back the client and tagged with
  23        the frontend syntax / schema.
  24       </p></li></ul></div><p>
  25    </p><p>
  26     The Retrieval facility is driven by an XML configuration. The
  27     configuration is neither Z39.50 ZeeRex or SRU ZeeRex. But it
  28     should be easy to generate both of them from the XML configuration.
  29     (unfortunately the two versions
  30     of ZeeRex differ substantially in this regard).
  31    </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="tools.retrieval.format"></a>6.1. Retrieval XML format</h3></div></div></div><p>
  32      All elements should be covered by namespace
  33      <code class="literal">http://indexdata.com/yaz</code> .
  34      The root element node must be <code class="literal">retrievalinfo</code>.
  35     </p><p>
  36      The <code class="literal">retrievalinfo</code> must include one or
  37      more <code class="literal">retrieval</code> elements. Each
  38     <code class="literal">retrieval</code> defines specific combination of
  39      syntax, name and identifier supported by this retrieval service.
  40     </p><p>
  41      The <code class="literal">retrieval</code> element may include any of the
  42      following attributes:
  43      </p><div class="variablelist"><dl><dt><span class="term"><code class="literal">syntax</code> (REQUIRED)</span></dt><dd><p>
  44          Defines the record syntax. Possible values is any
  45          of the names defined in YAZ' OID database or a raw
  46          OID in (n.n ... n).
  47         </p></dd><dt><span class="term"><code class="literal">name</code> (OPTIONAL)</span></dt><dd><p>
  48          Defines the name of the retrieval format. This can be
  49          any string. For SRU, the value, is equivalent to schema (short-hand);
  50          for Z39.50 it's equivalent to simple element set name.
  51         </p></dd><dt><span class="term"><code class="literal">identifier</code> (OPTIONAL)</span></dt><dd><p>
  52          Defines the URI schema name of the retrieval format. This can be
  53          any string. For SRU, the value, is equivalent to URI schema.
  54          For Z39.50, there is no equivalent.
  55         </p></dd></dl></div><p>
  56     </p><p>
  57      The <code class="literal">retrieval</code> may include one
  58      <code class="literal">backend</code> element. If a <code class="literal">backend</code>
  59      element is given, it specifies how the records are retrieved by
  60      some backend and how the records are converted from the backend to
  61      the "frontend".
  62     </p><p>
  63      The attributes, <code class="literal">name</code> and <code class="literal">syntax</code>
  64      may be specified for the <code class="literal">backend</code> element. These
  65      semantics of these attributes is equivalent to those for the
  66      <code class="literal">retrieval</code>. However, these values are passed to
  67      the "backend".
  68     </p><p>
  69      The <code class="literal">backend</code> element may includes one or more
  70      conversion instructions (as children elements). The supported
  71      conversions are:
  72      </p><div class="variablelist"><dl><dt><span class="term"><code class="literal">marc</code></span></dt><dd><p>
  73          The <code class="literal">marc</code> element specifies a conversion
  74          to - and from ISO2709 encoded MARC and
  75          <a class="ulink" href="http://www.loc.gov/standards/marcxml/" target="_top"><acronym class="acronym">MARCXML</acronym></a>/MarcXchange.
  76          The following attributes may be specified:
  77
  78          </p><div class="variablelist"><dl><dt><span class="term"><code class="literal">inputformat</code> (REQUIRED)</span></dt><dd><p>
  79              Format of input. Supported values are
  80             <code class="literal">marc</code> (for ISO2709); and <code class="literal">xml</code>
  81              for MARCXML/MarcXchange.
  82             </p></dd><dt><span class="term"><code class="literal">outputformat</code> (REQUIRED)</span></dt><dd><p>
  83              Format of output. Supported values are
  84             <code class="literal">line</code> (MARC line format);
  85             <code class="literal">marcxml</code> (for MARCXML),
  86             <code class="literal">marc</code> (ISO2709),
  87             <code class="literal">marcxhcange</code> (for MarcXchange).
  88             </p></dd><dt><span class="term"><code class="literal">inputcharset</code> (OPTIONAL)</span></dt><dd><p>
  89              Encoding of input. For XML input formats, this need not
  90              be given, but for ISO2709 based inputformats, this should
  91              be set to the encoding used. For MARC21 records, a common
  92              inputcharset value  would be <code class="literal">marc-8</code>.
  93             </p></dd><dt><span class="term"><code class="literal">outputcharset</code> (OPTIONAL)</span></dt><dd><p>
  94              Encoding of output. If outputformat is XML based, it is
  95              strongly recommened to use <code class="literal">utf-8</code>.
  96             </p></dd></dl></div><p>
  97         </p></dd><dt><span class="term"><code class="literal">xslt</code></span></dt><dd><p>
  98          The <code class="literal">xslt</code> element specifies a conversion
  99          via <acronym class="acronym">XSLT</acronym>. The following attributes may be specified:
 100
 101          </p><div class="variablelist"><dl><dt><span class="term"><code class="literal">stylesheet</code> (REQUIRED)</span></dt><dd><p>
 102              Stylesheet file.
 103             </p></dd></dl></div><p>
 104
 105         </p></dd></dl></div><p>
 106     </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="tools.retrieval.examples"></a>6.2. Retrieval Facility Examples</h3></div></div></div><div class="example"><a name="tools.retrieval.marc21"></a><p class="title"><b>Example 9.19. MARC21 backend</b></p><div class="example-contents"><p>
 107       A typical way to use the retrieval facility is to enable XML
 108       for servers that only supports ISO2709 encoded MARC21 records.
 109      </p><pre class="programlisting">
 110      &lt;retrievalinfo&gt;
 111        &lt;retrieval syntax="usmarc" name="F"/&gt;
 112        &lt;retrieval syntax="usmarc" name="B"/&gt;
 113        &lt;retrieval syntax="xml" name="marcxml"
 114                   identifier="info:srw/schema/1/marcxml-v1.1"&gt;
 115          &lt;backend syntax="usmarc" name="F"&gt;
 116            &lt;marc inputformat="marc" outputformat="marcxml"
 117                  inputcharset="marc-8"/&gt;
 118          &lt;/backend&gt;
 119        &lt;/retrieval&gt;
 120        &lt;retrieval syntax="xml" name="dc"&gt;
 121          &lt;backend syntax="usmarc" name="F"&gt;
 122            &lt;marc inputformat="marc" outputformat="marcxml"
 123                  inputcharset="marc-8"/&gt;
 124            &lt;xslt stylesheet="MARC21slim2DC.xsl"/&gt;
 125          &lt;/backend&gt;
 126        &lt;/retrieval&gt;
 127      &lt;/retrievalinfo&gt;
 128
 129      </pre><p>
 130       This means that our frontend supports:
 131       </p><div class="itemizedlist"><ul type="disc"><li><p>
 132          MARC21 F(ull) records.
 133         </p></li><li><p>
 134          MARC21 B(rief) records.
 135         </p></li><li><p>
 136          MARCXML records.
 137         </p></li><li><p>
 138          Dublin core records.
 139         </p></li></ul></div><p>
 140      </p></div></div><br class="example-break"></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="tools.retrieval.api"></a>6.3. API</h3></div></div></div><p>
 141      It should be easy to use the retrieval systems from applications. Refer
 142      to the headers
 143      <code class="filename">yaz/retrieval.h</code> and
 144      <code class="filename">yaz/record_conv.h</code>.
 145     </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="marc.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tools.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="odr.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5. MARC </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 10. The ODR Module</td></tr></table></div></body></html>