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