1 <?xml version="1.0" encoding="utf-8"?>
\r
2 <chapter xml:id="z3950" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"
\r
3 xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">
\r
5 <title><systemitem class="protocol">SRU</systemitem> and <systemitem class="protocol">Z39.50</systemitem> Server</title>
\r
7 <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
8 specific needs of your organization or consortium.</para>
\r
9 <section xml:id="Testing_SRU_yaz-client">
\r
11 <title>Testing SRU with yaz-client</title><indexterm><primary>yaz</primary></indexterm>
\r
13 <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
14 Evergreen ships an <systemitem class="protocol">SRU</systemitem> configuration <indexterm><primary>SRU</primary></indexterm>
\r
15 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
16 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
17 Evergreen server hostname:</para>
\r
18 <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
19 <link xlink:href="http://www.indexdata.com/yaz">http://www.indexdata.com/yaz</link>.</para></note>
\r
20 <screen><userinput>$ yaz-client http://dev.gapines.org/opac/extras/sru</userinput></screen>
\r
21 <screen><prompt>Z></prompt> <userinput>sru GET 1.1</userinput></screen>
\r
22 <screen><prompt>Z></prompt> <userinput>find hemingway</userinput></screen>
\r
24 <para>If your database has records that match that term, you will get the corresponding <systemitem>MARCXML</systemitem> records
\r
25 in your response from yaz-client.</para><indexterm><primary>MARCXML</primary></indexterm>
\r
26 <para>Here's what the SRU request looks like as sent to the Evergreen web server:</para>
\r
27 <screen><userinput>GET /opac/extras/sru?version=1.1&operation=searchRetrieve&query=hemingway&maximumRecords=0</userinput></screen>
\r
28 <para>You can see what the response looks like by hitting the same URL in your Web browser:
\r
29 <ulink url="http://dev.gapines.org/opac/extras/sru?version=1.1&operation=searchRetrieve&query=hemingway&maximumRecords=0">
\r
30 http://dev.gapines.org/opac/extras/sru?version=1.1&operation=searchRetrieve&query=hemingway&maximumRecords=0</ulink>
\r
31 <systemitem>CQL</systemitem> queries</para>
\r
32 <para>Evergreen supports some <systemitem>CQL</systemitem> <indexterm><primary>CQL</primary></indexterm> index-sets for advanced queries such as a subset of
\r
33 <systemitem>Dublin Core</systemitem> (DC) elements. Those DC elements that are
\r
34 supported map to Evergreen default indexes as follows:</para><indexterm><primary>Dublin Core</primary></indexterm>
\r
35 <informaltable xml:id="dc_elements">
\r
39 <entry>DC element </entry>
\r
40 <entry>Evergreen index</entry>
\r
45 <entry>title</entry>
\r
46 <entry>title</entry>
\r
49 <entry>creator </entry>
\r
50 <entry>author</entry>
\r
53 <entry>contributor</entry>
\r
54 <entry>author</entry>
\r
57 <entry>publisher</entry>
\r
58 <entry>keyword</entry>
\r
61 <entry>subject</entry>
\r
62 <entry>subject</entry>
\r
65 <entry>identifier</entry>
\r
66 <entry>keyword</entry>
\r
70 <entry>none</entry>
\r
73 <entry>format</entry>
\r
74 <entry>none</entry>
\r
77 <entry>language</entry>
\r
78 <entry>lang</entry>
\r
83 <para>Here are a few examples of <systemitem class="protocol">SRU</systemitem> searches against some of these indexes:</para>
\r
85 <listitem>dc.title all <quote>complete dinosaur</quote></listitem>
\r
86 <listitem>dc.subject all <quote>britain france</quote></listitem>
\r
87 <listitem>dc.title exact <quote>The Empire Strikes Back</quote></listitem>
\r
88 <listitem>dc.author=king and dc.title=zone</listitem>
\r
91 <section xml:id="Z3950serversupport">
\r
93 <title>Setting up <systemitem class="protocol">Z39.50</systemitem> server support</title><indexterm><primary>Z39.50</primary></indexterm>
\r
96 <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
98 <para>This support uses an <systemitem class="protocol">Z39.50</systemitem>-to-<systemitem class="protocol">SRU</systemitem> translator service supplied
\r
99 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
100 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
101 Evergreen <systemitem class="protocol">SRU</systemitem> server.</para>
\r
103 <title>Setting up the <systemitem class="protocol">Z39.50</systemitem> server</title>
\r
105 <para>Install a recent version of yaz (the Makefile.install should have installed a suitable version).</para></step>
\r
107 <para>Install <systemitem>Net::Z3950::Simple2ZOOM</systemitem> (<userinput>sudo cpan Net::Z3950::Simple2ZOOM</userinput>)</para></step>
\r
109 <para>Create a <systemitem class="daemon">Simple2ZOOM</systemitem> configuration file. Something like the following is a good start, and is
\r
110 based on the <systemitem class="daemon">Simple2ZOOM</systemitem>
\r
111 documentation example. We'll name the file <filename>dgo.conf</filename> for our example:</para>
\r
114 <database name="gapines">
\r
115 <zurl>http://dev.gapines.org/opac/extras/sru</zurl>
\r
116 <option name="sru">get</option>
\r
117 <charset>marc-8</charset>
\r
119 <querytype>cql</querytype>
\r
120 <map use="4"><index>eg.title</index></map>
\r
121 <map use="7"><index>eg.keyword</index></map>
\r
122 <map use="8"><index>eg.keyword</index></map>
\r
123 <map use="21"><index>eg.subject</index></map>
\r
124 <map use="1003"><index>eg.author</index></map>
\r
125 <map use="1018"><index>eg.publisher</index></map>
\r
126 <map use="1035"><index>eg.keyword</index></map>
\r
127 <map use="1016"><index>eg.keyword</index></map>
\r
132 <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
133 the <database> element is used in your <systemitem class="protocol">Z39.50</systemitem> connection string to name the database. The
\r
134 <systemitem><zurl></systemitem> element must point to
\r
135 <uri>http://hostname/opac/extras/sru</uri>. As of Evergreen 1.6, you can append an optional organization unit shortname for search
\r
136 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
137 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
138 to expose its holdings.</para>
\r
141 <para>Run <systemitem class="daemon">simple2ZOOM</systemitem> as a daemon, specifying the configuration files and one or more listener addresses that the
\r
142 <systemitem class="protocol">Z39.50</systemitem> server will
\r
143 be accessible on. If you do not specify a port, it will automatically run on port <systemitem>9999</systemitem>. In the following example,
\r
144 we tell it to listen both to localhost on port <systemitem>2210</systemitem>, and on <systemitem class="domainname">dev.gapines.org</systemitem>
\r
145 n port <systemitem>210</systemitem>:</para>
\r
148 <server id="server1">
\r
149 <retrievalinfo>
\r
150 <retrieval syntax="xml"/>
\r
151 <retrieval syntax="marc21">
\r
152 <backend syntax="xml">
\r
153 <marc inputformat="xml" outputformat="marc" inputcharset="utf-8" outputcharset="marc-8"/>
\r
156 </retrievalinfo>
\r
162 <para>Run <systemitem class="daemon">simple2ZOOM</systemitem> as a daemon, specifying the configuration files and one or more listener addresses that
\r
163 the <systemitem class="protocol">Z39.50</systemitem> server will be accessible on.
\r
164 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
165 <screen><userinput>simple2zoom -c dgo.conf -- -f xml2marc-yaz.cfg localhost:2210 dev.gapines.org:210</userinput></screen>
\r
168 <para>To test the <systemitem class="protocol">Z39.50</systemitem> server, we can use <application>yaz-client</application> again:</para>
\r
171 Z> open localhost:2210/gapines
\r
174 Connection accepted by v3 target.
\r
176 Name : Simple2ZOOM Universal Gateway/GFS/YAZ
\r
177 Version: 1.03/1.128/3.0.34
\r
178 Options: search present delSet triggerResourceCtrl scan sort namedResultSets
\r
180 Z> format marcxml
\r
181 Z> find <quote>dc.title=zone and dc.author=king</quote>
\r
182 Sent searchRequest.
\r
183 Received SearchResponse.
\r
184 Search was a success.
\r
185 Number of hits: 0, setno 4
\r
186 records returned: 0
\r
188 Z> find <quote>dead zone</quote>
\r
189 Sent searchRequest.
\r
190 Received SearchResponse.
\r
191 Search was a success.
\r
192 Number of hits: 4, setno 5
\r
193 records returned: 0
\r
196 Sent presentRequest (1+1).
\r
199 <record xmlns:... (rest of record deliberately truncated)
\r