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
37 <colspec colnum="1" colname="element" colwidth="1.0*"/>
\r
38 <colspec colnum="2" colname="EGindex" colwidth="1.0*"/>
\r
41 <entry>DC element </entry>
\r
42 <entry>Evergreen index</entry>
\r
47 <entry>title</entry>
\r
48 <entry>title</entry>
\r
51 <entry>creator </entry>
\r
52 <entry>author</entry>
\r
55 <entry>contributor</entry>
\r
56 <entry>author</entry>
\r
59 <entry>publisher</entry>
\r
60 <entry>keyword</entry>
\r
63 <entry>subject</entry>
\r
64 <entry>subject</entry>
\r
67 <entry>identifier</entry>
\r
68 <entry>keyword</entry>
\r
72 <entry>none</entry>
\r
75 <entry>format</entry>
\r
76 <entry>none</entry>
\r
79 <entry>language</entry>
\r
80 <entry>lang</entry>
\r
85 <para>Here are a few examples of <systemitem class="protocol">SRU</systemitem> searches against some of these indexes:</para>
\r
87 <listitem>dc.title all <quote>complete dinosaur</quote></listitem>
\r
88 <listitem>dc.subject all <quote>britain france</quote></listitem>
\r
89 <listitem>dc.title exact <quote>The Empire Strikes Back</quote></listitem>
\r
90 <listitem>dc.author=king and dc.title=zone</listitem>
\r
93 <section xml:id="Z3950serversupport">
\r
95 <title>Setting up <systemitem class="protocol">Z39.50</systemitem> server support</title><indexterm><primary>Z39.50</primary></indexterm>
\r
98 <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
100 <para>This support uses an <systemitem class="protocol">Z39.50</systemitem>-to-<systemitem class="protocol">SRU</systemitem> translator service supplied
\r
101 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
102 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
103 Evergreen <systemitem class="protocol">SRU</systemitem> server.</para>
\r
105 <title>Setting up the <systemitem class="protocol">Z39.50</systemitem> server</title>
\r
107 <para>Install a recent version of yaz (the Makefile.install should have installed a suitable version).</para></step>
\r
109 <para>Install <systemitem>Net::Z3950::Simple2ZOOM</systemitem> (<userinput>sudo cpan Net::Z3950::Simple2ZOOM</userinput>)</para></step>
\r
111 <para>Create a <systemitem class="daemon">Simple2ZOOM</systemitem> configuration file. Something like the following is a good start, and is
\r
112 based on the <systemitem class="daemon">Simple2ZOOM</systemitem>
\r
113 documentation example. We'll name the file <filename>dgo.conf</filename> for our example:</para>
\r
116 <database name="gapines">
\r
117 <zurl>http://dev.gapines.org/opac/extras/sru</zurl>
\r
118 <option name="sru">get</option>
\r
119 <charset>marc-8</charset>
\r
121 <querytype>cql</querytype>
\r
122 <map use="4"><index>eg.title</index></map>
\r
123 <map use="7"><index>eg.keyword</index></map>
\r
124 <map use="8"><index>eg.keyword</index></map>
\r
125 <map use="21"><index>eg.subject</index></map>
\r
126 <map use="1003"><index>eg.author</index></map>
\r
127 <map use="1018"><index>eg.publisher</index></map>
\r
128 <map use="1035"><index>eg.keyword</index></map>
\r
129 <map use="1016"><index>eg.keyword</index></map>
\r
134 <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
135 the <database> element is used in your <systemitem class="protocol">Z39.50</systemitem> connection string to name the database. The
\r
136 <systemitem><zurl></systemitem> element must point to
\r
137 <uri>http://hostname/opac/extras/sru</uri>. As of Evergreen 1.6, you can append an optional organization unit shortname for search
\r
138 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
139 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
140 to expose its holdings.</para>
\r
143 <para>Run <systemitem class="daemon">simple2ZOOM</systemitem> as a daemon, specifying the configuration files and one or more listener addresses that the
\r
144 <systemitem class="protocol">Z39.50</systemitem> server will
\r
145 be accessible on. If you do not specify a port, it will automatically run on port <systemitem>9999</systemitem>. In the following example,
\r
146 we tell it to listen both to localhost on port <systemitem>2210</systemitem>, and on <systemitem class="domainname">dev.gapines.org</systemitem>
\r
147 n port <systemitem>210</systemitem>:</para>
\r
150 <server id="server1">
\r
151 <retrievalinfo>
\r
152 <retrieval syntax="xml"/>
\r
153 <retrieval syntax="marc21">
\r
154 <backend syntax="xml">
\r
155 <marc inputformat="xml" outputformat="marc" inputcharset="utf-8" outputcharset="marc-8"/>
\r
158 </retrievalinfo>
\r
164 <para>Run <systemitem class="daemon">simple2ZOOM</systemitem> as a daemon, specifying the configuration files and one or more listener addresses that
\r
165 the <systemitem class="protocol">Z39.50</systemitem> server will be accessible on.
\r
166 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
167 <screen><userinput>simple2zoom -c dgo.conf -- -f xml2marc-yaz.cfg localhost:2210 dev.gapines.org:210</userinput></screen>
\r
170 <para>To test the <systemitem class="protocol">Z39.50</systemitem> server, we can use <application>yaz-client</application> again:</para>
\r
173 Z> open localhost:2210/gapines
\r
176 Connection accepted by v3 target.
\r
178 Name : Simple2ZOOM Universal Gateway/GFS/YAZ
\r
179 Version: 1.03/1.128/3.0.34
\r
180 Options: search present delSet triggerResourceCtrl scan sort namedResultSets
\r
182 Z> format marcxml
\r
183 Z> find <quote>dc.title=zone and dc.author=king</quote>
\r
184 Sent searchRequest.
\r
185 Received SearchResponse.
\r
186 Search was a success.
\r
187 Number of hits: 0, setno 4
\r
188 records returned: 0
\r
190 Z> find <quote>dead zone</quote>
\r
191 Sent searchRequest.
\r
192 Received SearchResponse.
\r
193 Search was a success.
\r
194 Number of hits: 4, setno 5
\r
195 records returned: 0
\r
198 Sent presentRequest (1+1).
\r
201 <record xmlns:... (rest of record deliberately truncated)
\r