+++ /dev/null
-<?xml version="1.0" encoding="utf-8"?>\r
-<chapter xml:id="z3950" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
- xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
- <info>\r
- <title><systemitem class="protocol">SRU</systemitem> and <systemitem class="protocol">Z39.50</systemitem> Server</title>\r
- </info>\r
- <para>Evergreen is extremely scalable and can serve the need of a large range of libraries. The specific requirements and configuration of your system should be determined based on your \r
- specific needs of your organization or consortium.</para>\r
- <section xml:id="Testing_SRU_yaz-client">\r
- <info>\r
- <title>Testing SRU with yaz-client</title><indexterm><primary>yaz</primary></indexterm>\r
- </info> \r
- <para>yaz-client is installed as a part of Index Data's YAZ software. Recent versions include support for querying <systemitem class="protocol">SRU</systemitem> servers. \r
- Evergreen ships an <systemitem class="protocol">SRU</systemitem> configuration <indexterm><primary>SRU</primary></indexterm>\r
- that works out of the box. To search Evergreen with yaz-client, choose the <emphasis>GET</emphasis> query method and issue the <command>find</command> command. \r
- In the following example, we connect to the Evergreen test server <systemitem class="domainname">dev.gapines.org</systemitem> - substitute this hostname with your own \r
- Evergreen server hostname:</para>\r
- <note><para>Some older versions of yaz-client have known issues with <systemitem class="protocol">SRU</systemitem>. Ensure that you are using the latest edition of yaz from \r
- <link xlink:href="http://www.indexdata.com/yaz">http://www.indexdata.com/yaz</link>.</para></note>\r
- <screen><userinput>$ yaz-client http://dev.gapines.org/opac/extras/sru</userinput></screen>\r
- <screen><prompt>Z></prompt> <userinput>sru GET 1.1</userinput></screen>\r
- <screen><prompt>Z></prompt> <userinput>find hemingway</userinput></screen>\r
- \r
- <para>If your database has records that match that term, you will get the corresponding <systemitem>MARCXML</systemitem> records \r
- in your response from yaz-client.</para><indexterm><primary>MARCXML</primary></indexterm>\r
- <para>Here's what the SRU request looks like as sent to the Evergreen web server:</para>\r
- <screen><userinput>GET /opac/extras/sru?version=1.1&operation=searchRetrieve&query=hemingway&maximumRecords=0</userinput></screen>\r
- <para>You can see what the response looks like by hitting the same URL in your Web browser: \r
- <ulink url="http://dev.gapines.org/opac/extras/sru?version=1.1&operation=searchRetrieve&query=hemingway&maximumRecords=0">\r
- http://dev.gapines.org/opac/extras/sru?version=1.1&operation=searchRetrieve&query=hemingway&maximumRecords=0</ulink>\r
- <systemitem>CQL</systemitem> queries</para>\r
- <para>Evergreen supports some <systemitem>CQL</systemitem> <indexterm><primary>CQL</primary></indexterm> index-sets for advanced queries such as a subset of \r
- <systemitem>Dublin Core</systemitem> (DC) elements. Those DC elements that are \r
- supported map to Evergreen default indexes as follows:</para><indexterm><primary>Dublin Core</primary></indexterm>\r
- <informaltable xml:id="dc_elements"> \r
- <tgroup cols="2">\r
- <colspec colnum="1" colname="element" colwidth="1.0*"/>\r
- <colspec colnum="2" colname="EGindex" colwidth="1.0*"/>\r
- <thead>\r
- <row>\r
- <entry>DC element </entry>\r
- <entry>Evergreen index</entry>\r
- </row>\r
- </thead>\r
- <tbody>\r
- <row>\r
- <entry>title</entry>\r
- <entry>title</entry> \r
- </row>\r
- <row>\r
- <entry>creator </entry>\r
- <entry>author</entry> \r
- </row>\r
- <row>\r
- <entry>contributor</entry>\r
- <entry>author</entry> \r
- </row>\r
- <row>\r
- <entry>publisher</entry>\r
- <entry>keyword</entry> \r
- </row>\r
- <row>\r
- <entry>subject</entry>\r
- <entry>subject</entry> \r
- </row>\r
- <row>\r
- <entry>identifier</entry>\r
- <entry>keyword</entry> \r
- </row>\r
- <row>\r
- <entry>type</entry>\r
- <entry>none</entry> \r
- </row>\r
- <row>\r
- <entry>format</entry>\r
- <entry>none</entry> \r
- </row>\r
- <row>\r
- <entry>language</entry>\r
- <entry>lang</entry> \r
- </row>\r
- </tbody>\r
- </tgroup>\r
- </informaltable>\r
- <para>Here are a few examples of <systemitem class="protocol">SRU</systemitem> searches against some of these indexes:</para>\r
- <itemizedlist>\r
- <listitem>dc.title all <quote>complete dinosaur</quote></listitem>\r
- <listitem>dc.subject all <quote>britain france</quote></listitem>\r
- <listitem>dc.title exact <quote>The Empire Strikes Back</quote></listitem>\r
- <listitem>dc.author=king and dc.title=zone</listitem>\r
- </itemizedlist>\r
- </section>\r
- <section xml:id="Z3950serversupport">\r
- <info>\r
- <title>Setting up <systemitem class="protocol">Z39.50</systemitem> server support</title><indexterm><primary>Z39.50</primary></indexterm>\r
- </info> \r
-\r
- <note><para>You must have Evergreen's <systemitem class="protocol">SRU</systemitem> server running before you can enable <systemitem>Z39.50</systemitem> server support.</para>\r
- </note> \r
- <para>This support uses an <systemitem class="protocol">Z39.50</systemitem>-to-<systemitem class="protocol">SRU</systemitem> translator service supplied \r
- by the <systemitem>Net::Z3950::Simple2ZOOM</systemitem><indexterm><primary>Simple2ZOOM</primary></indexterm> Perl module to enable Evergreen to act as a <systemitem class="protocol">Z39.50</systemitem> server. \r
- You could run the <systemitem class="protocol">Z39.50</systemitem> server on a different machine. It just needs to be able to connect to the \r
- Evergreen <systemitem class="protocol">SRU</systemitem> server.</para>\r
- <procedure>\r
- <title>Setting up the <systemitem class="protocol">Z39.50</systemitem> server</title>\r
- <step>\r
- <para>Install a recent version of yaz (the Makefile.install should have installed a suitable version).</para></step>\r
- <step>\r
- <para>Install <systemitem>Net::Z3950::Simple2ZOOM</systemitem> (<userinput>sudo cpan Net::Z3950::Simple2ZOOM</userinput>)</para></step>\r
- <step>\r
- <para>Create a <systemitem class="daemon">Simple2ZOOM</systemitem> configuration file. Something like the following is a good start, and is \r
- based on the <systemitem class="daemon">Simple2ZOOM</systemitem> \r
- documentation example. We'll name the file <filename>dgo.conf</filename> for our example:</para> \r
-<programlisting>\r
-<client>\r
- <database name="gapines">\r
- <zurl>http://dev.gapines.org/opac/extras/sru</zurl>\r
- <option name="sru">get</option>\r
- <charset>marc-8</charset>\r
- <search>\r
- <querytype>cql</querytype>\r
- <map use="4"><index>eg.title</index></map>\r
- <map use="7"><index>eg.keyword</index></map>\r
- <map use="8"><index>eg.keyword</index></map>\r
- <map use="21"><index>eg.subject</index></map>\r
- <map use="1003"><index>eg.author</index></map>\r
- <map use="1018"><index>eg.publisher</index></map>\r
- <map use="1035"><index>eg.keyword</index></map>\r
- <map use="1016"><index>eg.keyword</index></map>\r
- </search>\r
- </database>\r
-</client>\r
-</programlisting>\r
- <para>You can have multiple <database> sections in a single file, each pointing to a different scope of your consortium. The name attribute on \r
- the <database> element is used in your <systemitem class="protocol">Z39.50</systemitem> connection string to name the database. The \r
- <systemitem><zurl></systemitem> element must point to \r
- <uri>http://hostname/opac/extras/sru</uri>. As of Evergreen 1.6, you can append an optional organization unit shortname for search \r
- scoping purposes, and you can also append <emphasis>/holdings</emphasis> if you want to expose the holdings for any returned records. So your zurl \r
- could be <uri>http://dev.gapines.org/opac/extras/sru/BR1/holdings</uri> to limit the search scope to <emphasis role="bold">BR1</emphasis> and its children, and \r
- to expose its holdings.</para>\r
- </step>\r
- <step>\r
- <para>Run <systemitem class="daemon">simple2ZOOM</systemitem> as a daemon, specifying the configuration files and one or more listener addresses that the \r
- <systemitem class="protocol">Z39.50</systemitem> server will\r
- be accessible on. If you do not specify a port, it will automatically run on port <systemitem>9999</systemitem>. In the following example, \r
- we tell it to listen both to localhost on port <systemitem>2210</systemitem>, and on <systemitem class="domainname">dev.gapines.org</systemitem> \r
- n port <systemitem>210</systemitem>:</para>\r
-<programlisting>\r
- <yazgfs>\r
- <server id="server1">\r
- <retrievalinfo>\r
- <retrieval syntax="xml"/>\r
- <retrieval syntax="marc21">\r
- <backend syntax="xml">\r
- <marc inputformat="xml" outputformat="marc" inputcharset="utf-8" outputcharset="marc-8"/>\r
- </backend>\r
- </retrieval>\r
- </retrievalinfo>\r
- </server>\r
-</yazgfs>\r
-</programlisting>\r
- </step>\r
- <step>\r
- <para>Run <systemitem class="daemon">simple2ZOOM</systemitem> as a daemon, specifying the configuration files and one or more listener addresses that \r
- the <systemitem class="protocol">Z39.50</systemitem> server will be accessible on. \r
- If you do not specify a port, it will automatically run on port <systemitem>9999</systemitem>. In the following example, we tell it to listen both to localhost on port 2210, and on dev.gapines.org on port <systemitem>210</systemitem>:</para>\r
- <screen><userinput>simple2zoom -c dgo.conf -- -f xml2marc-yaz.cfg localhost:2210 dev.gapines.org:210</userinput></screen>\r
- </step> \r
- </procedure>\r
- <para>To test the <systemitem class="protocol">Z39.50</systemitem> server, we can use <application>yaz-client</application> again:</para>\r
-<screen>\r
-yaz-client\r
-Z> open localhost:2210/gapines\r
-Connecting...OK.\r
-Sent initrequest.\r
-Connection accepted by v3 target.\r
-ID : 81/81\r
-Name : Simple2ZOOM Universal Gateway/GFS/YAZ\r
-Version: 1.03/1.128/3.0.34\r
-Options: search present delSet triggerResourceCtrl scan sort namedResultSets\r
-Elapsed: 0.010718\r
-Z> format marcxml\r
-Z> find <quote>dc.title=zone and dc.author=king</quote>\r
-Sent searchRequest.\r
-Received SearchResponse.\r
-Search was a success.\r
-Number of hits: 0, setno 4\r
-records returned: 0\r
-Elapsed: 0.611432\r
-Z> find <quote>dead zone</quote>\r
-Sent searchRequest.\r
-Received SearchResponse.\r
-Search was a success.\r
-Number of hits: 4, setno 5\r
-records returned: 0\r
-Elapsed: 1.555461\r
-Z> show 1\r
-Sent presentRequest (1+1).\r
-Records: 1\r
-[]Record type: XML\r
-<record xmlns:... (rest of record deliberately truncated)\r
-</screen>\r
- </section>\r
-</chapter>\r
-\r