2.0/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                                 <colspec colnum="1" colname="element" colwidth="1.0*"/>\r
  38                                 <colspec colnum="2" colname="EGindex" colwidth="1.0*"/>\r
  39                                 <thead>\r
  40                                         <row>\r
  41                                                 <entry>DC element </entry>\r
  42                                                 <entry>Evergreen index</entry>\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 <systemitem class="protocol">SRU</systemitem> 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         </section>\r
  93         <section xml:id="Z3950serversupport">\r
  94                 <info>\r
  95                     <title>Setting up <systemitem class="protocol">Z39.50</systemitem> server support</title><indexterm><primary>Z39.50</primary></indexterm>\r
  96                 </info> \r
  97 \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
  99                         </note>                  \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
 104                         <procedure>\r
 105                                 <title>Setting up the <systemitem class="protocol">Z39.50</systemitem> server</title>\r
 106                                 <step>\r
 107                                         <para>Install a recent version of yaz (the Makefile.install should have installed a suitable version).</para></step>\r
 108                                 <step>\r
 109                                         <para>Install <systemitem>Net::Z3950::Simple2ZOOM</systemitem> (<userinput>sudo cpan Net::Z3950::Simple2ZOOM</userinput>)</para></step>\r
 110                                 <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
 114 <programlisting>\r
 115 &lt;client&gt;\r
 116         &lt;database name="gapines"&gt;\r
 117                 &lt;zurl&gt;http://dev.gapines.org/opac/extras/sru&lt;/zurl&gt;\r
 118                 &lt;option name="sru"&gt;get&lt;/option&gt;\r
 119                 &lt;charset&gt;marc-8&lt;/charset&gt;\r
 120                 &lt;search&gt;\r
 121                         &lt;querytype&gt;cql&lt;/querytype&gt;\r
 122                         &lt;map use="4"&gt;&lt;index&gt;eg.title&lt;/index&gt;&lt;/map&gt;\r
 123                         &lt;map use="7"&gt;&lt;index&gt;eg.keyword&lt;/index&gt;&lt;/map&gt;\r
 124                         &lt;map use="8"&gt;&lt;index&gt;eg.keyword&lt;/index&gt;&lt;/map&gt;\r
 125                         &lt;map use="21"&gt;&lt;index&gt;eg.subject&lt;/index&gt;&lt;/map&gt;\r
 126                         &lt;map use="1003"&gt;&lt;index&gt;eg.author&lt;/index&gt;&lt;/map&gt;\r
 127                         &lt;map use="1018"&gt;&lt;index&gt;eg.publisher&lt;/index&gt;&lt;/map&gt;\r
 128                         &lt;map use="1035"&gt;&lt;index&gt;eg.keyword&lt;/index&gt;&lt;/map&gt;\r
 129                         &lt;map use="1016"&gt;&lt;index&gt;eg.keyword&lt;/index&gt;&lt;/map&gt;\r
 130                 &lt;/search&gt;\r
 131         &lt;/database&gt;\r
 132 &lt;/client&gt;\r
 133 </programlisting>\r
 134                                         <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
 135                                         the &lt;database&gt; element is used in your <systemitem class="protocol">Z39.50</systemitem> connection string to name the database. The \r
 136                                         <systemitem>&lt;zurl&gt;</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
 141                                 </step>\r
 142                                 <step>\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
 148 <programlisting>\r
 149  &lt;yazgfs&gt;\r
 150         &lt;server id="server1"&gt;\r
 151                 &lt;retrievalinfo&gt;\r
 152                         &lt;retrieval syntax="xml"/&gt;\r
 153                         &lt;retrieval syntax="marc21"&gt;\r
 154                         &lt;backend syntax="xml"&gt;\r
 155                                 &lt;marc inputformat="xml" outputformat="marc" inputcharset="utf-8" outputcharset="marc-8"/&gt;\r
 156                         &lt;/backend&gt;\r
 157                         &lt;/retrieval&gt;\r
 158                 &lt;/retrievalinfo&gt;\r
 159         &lt;/server&gt;\r
 160 &lt;/yazgfs&gt;\r
 161 </programlisting>\r
 162                                 </step>\r
 163                                 <step>\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
 168                                 </step>                         \r
 169                         </procedure>\r
 170                         <para>To test the <systemitem class="protocol">Z39.50</systemitem> server, we can use <application>yaz-client</application> again:</para>\r
 171 <screen>\r
 172 yaz-client\r
 173 Z&gt; open localhost:2210/gapines\r
 174 Connecting...OK.\r
 175 Sent initrequest.\r
 176 Connection accepted by v3 target.\r
 177 ID     : 81/81\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
 181 Elapsed: 0.010718\r
 182 Z&gt; format marcxml\r
 183 Z&gt; 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
 189 Elapsed: 0.611432\r
 190 Z&gt; 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
 196 Elapsed: 1.555461\r
 197 Z&gt; show 1\r
 198 Sent presentRequest (1+1).\r
 199 Records: 1\r
 200 []Record type: XML\r
 201 &lt;record xmlns:... (rest of record deliberately truncated)\r
 202 </screen>\r
 203         </section>\r
 204 </chapter>\r
 205 \r