More admin clean up...
[working/Evergreen.git] / 1.6 / admin / z3950.xml
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
4     <info>\r
5         <title><systemitem class="protocol">SRU</systemitem> and <systemitem class="protocol">Z39.50</systemitem> Server</title>\r
6     </info>\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
10                 <info>\r
11                     <title>Testing SRU with yaz-client</title><indexterm><primary>yaz</primary></indexterm>\r
12                 </info> \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
23                         \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&amp;operation=searchRetrieve&amp;query=hemingway&amp;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&amp;operation=searchRetrieve&amp;query=hemingway&amp;maximumRecords=0">\r
30                         http://dev.gapines.org/opac/extras/sru?version=1.1&amp;operation=searchRetrieve&amp;query=hemingway&amp;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
36                         <tgroup cols="2">\r
37                                 <thead>\r
38                                         <row>\r
39                                                 <entry>DC element </entry>\r
40                                                 <entry>Evergreen index</entry>\r
41                                         </row>\r
42                                 </thead>\r
43                                 <tbody>\r
44                                         <row>\r
45                                                 <entry>title</entry>\r
46                                                 <entry>title</entry>                            \r
47                                         </row>\r
48                                         <row>\r
49                                                 <entry>creator </entry>\r
50                                                 <entry>author</entry>                           \r
51                                         </row>\r
52                                         <row>\r
53                                                 <entry>contributor</entry>\r
54                                                 <entry>author</entry>                           \r
55                                         </row>\r
56                                         <row>\r
57                                                 <entry>publisher</entry>\r
58                                                 <entry>keyword</entry>                          \r
59                                         </row>\r
60                                         <row>\r
61                                                 <entry>subject</entry>\r
62                                                 <entry>subject</entry>                          \r
63                                         </row>\r
64                                         <row>\r
65                                                 <entry>identifier</entry>\r
66                                                 <entry>keyword</entry>                          \r
67                                         </row>\r
68                                         <row>\r
69                                                 <entry>type</entry>\r
70                                                 <entry>none</entry>                             \r
71                                         </row>\r
72                                         <row>\r
73                                                 <entry>format</entry>\r
74                                                 <entry>none</entry>                             \r
75                                         </row>\r
76                                         <row>\r
77                                                 <entry>language</entry>\r
78                                                 <entry>lang</entry>                             \r
79                                         </row>\r
80                                 </tbody>\r
81                         </tgroup>\r
82                         </informaltable>\r
83                         <para>Here are a few examples of <systemitem class="protocol">SRU</systemitem> searches against some of these indexes:</para>\r
84                         <itemizedlist>\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
89                         </itemizedlist>\r
90         </section>\r
91         <section xml:id="Z3950serversupport">\r
92                 <info>\r
93                     <title>Setting up <systemitem class="protocol">Z39.50</systemitem> server support</title><indexterm><primary>Z39.50</primary></indexterm>\r
94                 </info> \r
95 \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
97                         </note>                  \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
102                         <procedure>\r
103                                 <title>Setting up the <systemitem class="protocol">Z39.50</systemitem> server</title>\r
104                                 <step>\r
105                                         <para>Install a recent version of yaz (the Makefile.install should have installed a suitable version).</para></step>\r
106                                 <step>\r
107                                         <para>Install <systemitem>Net::Z3950::Simple2ZOOM</systemitem> (<userinput>sudo cpan Net::Z3950::Simple2ZOOM</userinput>)</para></step>\r
108                                 <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
112 <programlisting>\r
113 &lt;client&gt;\r
114         &lt;database name="gapines"&gt;\r
115                 &lt;zurl&gt;http://dev.gapines.org/opac/extras/sru&lt;/zurl&gt;\r
116                 &lt;option name="sru"&gt;get&lt;/option&gt;\r
117                 &lt;charset&gt;marc-8&lt;/charset&gt;\r
118                 &lt;search&gt;\r
119                         &lt;querytype&gt;cql&lt;/querytype&gt;\r
120                         &lt;map use="4"&gt;&lt;index&gt;eg.title&lt;/index&gt;&lt;/map&gt;\r
121                         &lt;map use="7"&gt;&lt;index&gt;eg.keyword&lt;/index&gt;&lt;/map&gt;\r
122                         &lt;map use="8"&gt;&lt;index&gt;eg.keyword&lt;/index&gt;&lt;/map&gt;\r
123                         &lt;map use="21"&gt;&lt;index&gt;eg.subject&lt;/index&gt;&lt;/map&gt;\r
124                         &lt;map use="1003"&gt;&lt;index&gt;eg.author&lt;/index&gt;&lt;/map&gt;\r
125                         &lt;map use="1018"&gt;&lt;index&gt;eg.publisher&lt;/index&gt;&lt;/map&gt;\r
126                         &lt;map use="1035"&gt;&lt;index&gt;eg.keyword&lt;/index&gt;&lt;/map&gt;\r
127                         &lt;map use="1016"&gt;&lt;index&gt;eg.keyword&lt;/index&gt;&lt;/map&gt;\r
128                 &lt;/search&gt;\r
129         &lt;/database&gt;\r
130 &lt;/client&gt;\r
131 </programlisting>\r
132                                         <para>You can have multiple &lt;database&gt; sections in a single file, each pointing to a different scope of your consortium. The name attribute on \r
133                                         the &lt;database&gt; element is used in your <systemitem class="protocol">Z39.50</systemitem> connection string to name the database. The \r
134                                         <systemitem>&lt;zurl&gt;</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
139                                 </step>\r
140                                 <step>\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
146 <programlisting>\r
147  &lt;yazgfs&gt;\r
148         &lt;server id="server1"&gt;\r
149                 &lt;retrievalinfo&gt;\r
150                         &lt;retrieval syntax="xml"/&gt;\r
151                         &lt;retrieval syntax="marc21"&gt;\r
152                         &lt;backend syntax="xml"&gt;\r
153                                 &lt;marc inputformat="xml" outputformat="marc" inputcharset="utf-8" outputcharset="marc-8"/&gt;\r
154                         &lt;/backend&gt;\r
155                         &lt;/retrieval&gt;\r
156                 &lt;/retrievalinfo&gt;\r
157         &lt;/server&gt;\r
158 &lt;/yazgfs&gt;\r
159 </programlisting>\r
160                                 </step>\r
161                                 <step>\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
166                                 </step>                         \r
167                         </procedure>\r
168                         <para>To test the <systemitem class="protocol">Z39.50</systemitem> server, we can use <application>yaz-client</application> again:</para>\r
169 <screen>\r
170 yaz-client\r
171 Z&gt; open localhost:2210/gapines\r
172 Connecting...OK.\r
173 Sent initrequest.\r
174 Connection accepted by v3 target.\r
175 ID     : 81/81\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
179 Elapsed: 0.010718\r
180 Z&gt; format marcxml\r
181 Z&gt; 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
187 Elapsed: 0.611432\r
188 Z&gt; 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
194 Elapsed: 1.555461\r
195 Z&gt; show 1\r
196 Sent presentRequest (1+1).\r
197 Records: 1\r
198 []Record type: XML\r
199 &lt;record xmlns:... (rest of record deliberately truncated)\r
200 </screen>\r
201         </section>\r
202 </chapter>\r
203 \r