f2d99dd1b9bba695d6335e55ac16cb9427da932b
[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>SRU and Z39.50 Server</title>\r
6     </info>\r
7 \r
8     <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
9         specific needs of your organization or consortium.</para>\r
10                 \r
11     \r
12         <section xml:id="Testing_SRU_yaz-client">\r
13                 <info>\r
14                     <title>Testing SRU with yaz-client</title>\r
15                 </info> \r
16                          <para>yaz-client is installed as a part of Index Data's YAZ software. Recent versions include support for querying SRU servers. Evergreen ships an SRU configuration \r
17                         that works out of the box. To search Evergreen with yaz-client, choose the <emphasis>GET</emphasis> query method and issue the <emphasis>find</emphasis> command. \r
18                         In the following example, we connect to the Evergreen test server <emphasis>dev.gapines.org</emphasis>; substitute this hostname with your own Evergreen server \r
19                         hostname:</para>\r
20                         <note><para>Some older versions of yaz-client have known issues with SRU. Ensure that you are using the latest edition of yaz from \r
21                         <link xlink:href="http://www.indexdata.com/yaz">http://www.indexdata.com/yaz</link>.</para></note>\r
22                         <screen>$ yaz-client http://dev.gapines.org/opac/extras/sru</screen>\r
23                         <screen>Z> sru GET 1.1</screen>\r
24                         <screen>Z> find hemingway</screen>\r
25                         \r
26                          <para>If your database has records that match that term, you will get the corresponding MARCXML records in your response from yaz-client.</para>\r
27                          <para>Here's what the SRU request looks like as sent to the Evergreen web server:</para>\r
28                          <screen>GET /opac/extras/sru?version=1.1&amp;operation=searchRetrieve&amp;query=hemingway&amp;maximumRecords=0</screen>\r
29                         <para>You can see what the response looks like by hitting the same URL in your Web browser: \r
30                         <ulink url="http://dev.gapines.org/opac/extras/sru?version=1.1&amp;operation=searchRetrieve&amp;query=hemingway&amp;maximumRecords=0">\r
31                         http://dev.gapines.org/opac/extras/sru?version=1.1&amp;operation=searchRetrieve&amp;query=hemingway&amp;maximumRecords=0</ulink>\r
32                         CQL queries</para>\r
33                          <para>Evergreen supports some CQL index-sets for advanced queries such as a subset of Dublin Core (DC) elements. Those DC elements that are \r
34                         supported map to Evergreen default indexes as follows:</para>\r
35                         <informaltable xml:id="dc_elements">\r
36                         \r
37                         <tgroup cols="2">\r
38                                 <thead>\r
39                                         <row>\r
40                                                 <entry>DC element </entry>\r
41                                                 <entry>Evergreen index</entry>\r
42                                                 \r
43                                         </row>\r
44                                 </thead>\r
45                                 <tbody>\r
46                                         <row>\r
47                                                 <entry>title</entry>\r
48                                                 <entry>title</entry>                            \r
49                                         </row>\r
50                                         <row>\r
51                                                 <entry>creator </entry>\r
52                                                 <entry>author</entry>                           \r
53                                         </row>\r
54                                         <row>\r
55                                                 <entry>contributor</entry>\r
56                                                 <entry>author</entry>                           \r
57                                         </row>\r
58                                         <row>\r
59                                                 <entry>publisher</entry>\r
60                                                 <entry>keyword</entry>                          \r
61                                         </row>\r
62                                         <row>\r
63                                                 <entry>subject</entry>\r
64                                                 <entry>subject</entry>                          \r
65                                         </row>\r
66                                         <row>\r
67                                                 <entry>identifier</entry>\r
68                                                 <entry>keyword</entry>                          \r
69                                         </row>\r
70                                         <row>\r
71                                                 <entry>type</entry>\r
72                                                 <entry>none</entry>                             \r
73                                         </row>\r
74                                         <row>\r
75                                                 <entry>format</entry>\r
76                                                 <entry>none</entry>                             \r
77                                         </row>\r
78                                         <row>\r
79                                                 <entry>language</entry>\r
80                                                 <entry>lang</entry>                             \r
81                                         </row>\r
82                                 </tbody>\r
83                         </tgroup>\r
84                         </informaltable>\r
85                         <para>Here are a few examples of SRU searches against some of these indexes:</para>\r
86                         <itemizedlist>\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
91                         </itemizedlist>\r
92 \r
93         </section>\r
94         <section xml:id="Z3950serversupport">\r
95                 <info>\r
96                     <title>Setting up Z39.50 server support</title>\r
97                 </info> \r
98 \r
99                         <note><para>You must have Evergreen's SRU server running before you can enable Z39.50 server support.</para></note>                      \r
100                         <para>This support uses an Z39.50-to-SRU translator service supplied by the <emphasis>Net::Z3950::Simple2ZOOM</emphasis> Perl module to enable Evergreen to act as a Z39.50 server. \r
101                         You could run the Z39.50 server on a different machine. It just needs to be able to connect to the Evergreen SRU server.</para>\r
102                         <procedure>\r
103                                 <title>Setting up the Z39.50 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 Net::Z3950::Simple2ZOOM (sudo cpan Net::Z3950::Simple2ZOOM)</para></step>\r
108                                 <step>\r
109                                         <para>Create a Simple2ZOOM configuration file. Something like the following is a good start, and is based on the Simple2ZOOM documentation example. \r
110                                         We'll name the file dgo.conf for our example:</para>    \r
111                                         <programlisting>\r
112                                         &lt;client&gt;\r
113                                                 &lt;database name="gapines"&gt;\r
114                                                         &lt;zurl&gt;http://dev.gapines.org/opac/extras/sru&lt;/zurl&gt;\r
115                                                         &lt;option name="sru"&gt;get&lt;/option&gt;\r
116                                                         &lt;charset&gt;marc-8&lt;/charset&gt;\r
117                                                         &lt;search&gt;\r
118                                                                 &lt;querytype&gt;cql&lt;/querytype&gt;\r
119                                                                 &lt;map use="4"&gt;&lt;index&gt;eg.title&lt;/index&gt;&lt;/map&gt;\r
120                                                                 &lt;map use="7"&gt;&lt;index&gt;eg.keyword&lt;/index&gt;&lt;/map&gt;\r
121                                                                 &lt;map use="8"&gt;&lt;index&gt;eg.keyword&lt;/index&gt;&lt;/map&gt;\r
122                                                                 &lt;map use="21"&gt;&lt;index&gt;eg.subject&lt;/index&gt;&lt;/map&gt;\r
123                                                                 &lt;map use="1003"&gt;&lt;index&gt;eg.author&lt;/index&gt;&lt;/map&gt;\r
124                                                                 &lt;map use="1018"&gt;&lt;index&gt;eg.publisher&lt;/index&gt;&lt;/map&gt;\r
125                                                                 &lt;map use="1035"&gt;&lt;index&gt;eg.keyword&lt;/index&gt;&lt;/map&gt;\r
126                                                                 &lt;map use="1016"&gt;&lt;index&gt;eg.keyword&lt;/index&gt;&lt;/map&gt;\r
127                                                         &lt;/search&gt;\r
128                                                 &lt;/database&gt;\r
129                                         &lt;/client&gt;\r
130                                         </programlisting>\r
131                                         <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
132                                         the &lt;database&gt; element is used in your Z39.50 connection string to name the database. The &lt;zurl&gt; element must point to \r
133                                         <emphasis>http://hostname/opac/extras/sru</emphasis>. As of Evergreen 1.6, you can append an optional organization unit shortname for search \r
134                                         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
135                                         could be <emphasis>http://dev.gapines.org/opac/extras/sru/BR1/holdings</emphasis> to limit the search scope to BR1 and its children, and \r
136                                         to expose its holdings.</para>\r
137                                 </step>\r
138                                 <step>\r
139                                         <para>Run simple2ZOOM as a daemon, specifying the configuration files and one or more listener addresses that the Z39.50 server will be accessible on. \r
140                                         If you do not specify a port, it will automatically run on port 9999. In the following example, we tell it to listen both to localhost on port 2210, \r
141                                         and on dev.gapines.org on port 210:</para>\r
142                                         <programlisting>\r
143                                          &lt;yazgfs&gt;\r
144                                                 &lt;server id="server1"&gt;\r
145                                                         &lt;retrievalinfo&gt;\r
146                                                                 &lt;retrieval syntax="xml"/&gt;\r
147                                                                 &lt;retrieval syntax="marc21"&gt;\r
148                                                                 &lt;backend syntax="xml"&gt;\r
149                                                                         &lt;marc inputformat="xml" outputformat="marc" inputcharset="utf-8" outputcharset="marc-8"/&gt;\r
150                                                                 &lt;/backend&gt;\r
151                                                                 &lt;/retrieval&gt;\r
152                                                         &lt;/retrievalinfo&gt;\r
153                                                 &lt;/server&gt;\r
154                                         &lt;/yazgfs&gt;\r
155                                         </programlisting>\r
156                                 </step>\r
157                                 <step>\r
158                                         <para>Run simple2ZOOM as a daemon, specifying the configuration files and one or more listener addresses that the Z39.50 server will be accessible on. \r
159                                         If you do not specify a port, it will automatically run on port 9999. In the following example, we tell it to listen both to localhost on port 2210, \r
160                                         and on dev.gapines.org on port 210:</para>\r
161                                         <command>simple2zoom -c dgo.conf -- -f xml2marc-yaz.cfg localhost:2210 dev.gapines.org:210</command>\r
162                                 </step>                         \r
163                         </procedure>\r
164                         <para>To test the Z39.50 server, we can use yaz-client again:</para>\r
165                         <screen>\r
166                         yaz-client\r
167                         Z&gt; open localhost:2210/gapines\r
168                         Connecting...OK.\r
169                         Sent initrequest.\r
170                         Connection accepted by v3 target.\r
171                         ID     : 81/81\r
172                         Name   : Simple2ZOOM Universal Gateway/GFS/YAZ\r
173                         Version: 1.03/1.128/3.0.34\r
174                         Options: search present delSet triggerResourceCtrl scan sort namedResultSets\r
175                         Elapsed: 0.010718\r
176                         Z&gt; format marcxml\r
177                         Z&gt; find <quote>dc.title=zone and dc.author=king</quote>\r
178                         Sent searchRequest.\r
179                         Received SearchResponse.\r
180                         Search was a success.\r
181                         Number of hits: 0, setno 4\r
182                         records returned: 0\r
183                         Elapsed: 0.611432\r
184                         Z&gt; find <quote>dead zone</quote>\r
185                         Sent searchRequest.\r
186                         Received SearchResponse.\r
187                         Search was a success.\r
188                         Number of hits: 4, setno 5\r
189                         records returned: 0\r
190                         Elapsed: 1.555461\r
191                         Z&gt; show 1\r
192                         Sent presentRequest (1+1).\r
193                         Records: 1\r
194                         []Record type: XML\r
195                         &lt;record xmlns:... (rest of record deliberately truncated)\r
196                         </screen>\r
197         </section>\r
198 </chapter>\r
199 \r