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         <section xml:id="Testing_SRU_yaz-client">\r
  12                 <info>\r
  13                     <title>Testing SRU with yaz-client</title>\r
  14                 </info> \r
  15                          <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
  16                         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
  17                         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
  18                         hostname:</para>\r
  19                         <screen>\r
  20                         $ yaz-client http://dev.gapines.org/opac/extras/sru\r
  21                         Z> sru GET 1.1\r
  22                         Z> find hemingway\r
  23                         </screen>\r
  24                          <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
  25                          <para>Here's what the SRU request looks like as sent to the Evergreen web server:</para>\r
  26                          <screen>GET /opac/extras/sru?version=1.1&amp;operation=searchRetrieve&amp;query=hemingway&amp;maximumRecords=0</screen>\r
  27                         <para>You can see what the response looks like by hitting the same URL in your Web browser: \r
  28                         <ulink url="http://dev.gapines.org/opac/extras/sru?version=1.1&amp;operation=searchRetrieve&amp;query=hemingway&amp;maximumRecords=0">\r
  29                         http://dev.gapines.org/opac/extras/sru?version=1.1&amp;operation=searchRetrieve&amp;query=hemingway&amp;maximumRecords=0</ulink>\r
  30                         CQL queries</para>\r
  31                          <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
  32                         supported map to Evergreen default indexes as follows:</para>\r
  33                         <informaltable xml:id="dc_elements">\r
  34                         \r
  35                         <tgroup cols="2">\r
  36                                 <thead>\r
  37                                         <row>\r
  38                                                 <entry>DC element </entry>\r
  39                                                 <entry>Evergreen index</entry>\r
  40                                                 \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 SRU 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 \r
  91         </section>\r
  92         <section xml:id="Z3950serversupport">\r
  93                 <info>\r
  94                     <title>Setting up Z39.50 server support</title>\r
  95                 </info> \r
  96 \r
  97                         <note><para>You must have Evergreen's SRU server running before you can enable Z39.50 server support.</para></note>                      \r
  98                         <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
  99                         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
 100                         <procedure>\r
 101                                 <title>Setting up the Z39.50 server</title>\r
 102                                 <step>\r
 103                                         <para>Install a recent version of yaz (the Makefile.install should have installed a suitable version).</para></step>\r
 104                                 <step>\r
 105                                         <para>Install Net::Z3950::Simple2ZOOM (sudo cpan Net::Z3950::Simple2ZOOM)</para></step>\r
 106                                 <step>\r
 107                                         <para>Create a Simple2ZOOM configuration file. Something like the following is a good start, and is based on the Simple2ZOOM documentation example. \r
 108                                         We'll name the file dgo.conf for our example:</para>    \r
 109                                         <screen>\r
 110                                         &lt;client&gt;\r
 111                                                 &lt;database name="gapines"&gt;\r
 112                                                         &lt;zurl&gt;http://dev.gapines.org/opac/extras/sru&lt;/zurl&gt;\r
 113                                                         &lt;option name="sru"&gt;get&lt;/option&gt;\r
 114                                                         &lt;charset&gt;marc-8&lt;/charset&gt;\r
 115                                                         &lt;search&gt;\r
 116                                                                 &lt;querytype&gt;cql&lt;/querytype&gt;\r
 117                                                                 &lt;map use="4"&gt;&lt;index&gt;eg.title&lt;/index&gt;&lt;/map&gt;\r
 118                                                                 &lt;map use="7"&gt;&lt;index&gt;eg.keyword&lt;/index&gt;&lt;/map&gt;\r
 119                                                                 &lt;map use="8"&gt;&lt;index&gt;eg.keyword&lt;/index&gt;&lt;/map&gt;\r
 120                                                                 &lt;map use="21"&gt;&lt;index&gt;eg.subject&lt;/index&gt;&lt;/map&gt;\r
 121                                                                 &lt;map use="1003"&gt;&lt;index&gt;eg.author&lt;/index&gt;&lt;/map&gt;\r
 122                                                                 &lt;map use="1018"&gt;&lt;index&gt;eg.publisher&lt;/index&gt;&lt;/map&gt;\r
 123                                                                 &lt;map use="1035"&gt;&lt;index&gt;eg.keyword&lt;/index&gt;&lt;/map&gt;\r
 124                                                                 &lt;map use="1016"&gt;&lt;index&gt;eg.keyword&lt;/index&gt;&lt;/map&gt;\r
 125                                                         &lt;/search&gt;\r
 126                                                 &lt;/database&gt;\r
 127                                         &lt;/client&gt;\r
 128                                         </screen>\r
 129                                         <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
 130                                         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
 131                                         <emphasis>http://hostname/opac/extras/sru</emphasis>. As of Evergreen 1.6, you can append an optional organization unit shortname for search \r
 132                                         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
 133                                         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
 134                                         to expose its holdings.</para>\r
 135                                 </step>\r
 136                                 <step>\r
 137                                         <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
 138                                         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
 139                                         and on dev.gapines.org on port 210:</para>\r
 140                                         <screen>\r
 141                                          &lt;yazgfs&gt;\r
 142                                                 &lt;server id="server1"&gt;\r
 143                                                         &lt;retrievalinfo&gt;\r
 144                                                                 &lt;retrieval syntax="xml"/&gt;\r
 145                                                                 &lt;retrieval syntax="marc21"&gt;\r
 146                                                                 &lt;backend syntax="xml"&gt;\r
 147                                                                         &lt;marc inputformat="xml" outputformat="marc" inputcharset="utf-8" outputcharset="marc-8"/&gt;\r
 148                                                                 &lt;/backend&gt;\r
 149                                                                 &lt;/retrieval&gt;\r
 150                                                         &lt;/retrievalinfo&gt;\r
 151                                                 &lt;/server&gt;\r
 152                                         &lt;/yazgfs&gt;\r
 153                                         </screen>\r
 154                                 </step>\r
 155                                 <step>\r
 156                                         <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
 157                                         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
 158                                         and on dev.gapines.org on port 210:</para>\r
 159                                         <command>simple2zoom -c dgo.conf -- -f xml2marc-yaz.cfg localhost:2210 dev.gapines.org:210</command>\r
 160                                 </step>                         \r
 161                         </procedure>\r
 162                         <para>To test the Z39.50 server, we can use yaz-client again:</para>]\r
 163                         <screen>\r
 164                         yaz-client\r
 165                         Z&gt; open localhost:2210/gapines\r
 166                         Connecting...OK.\r
 167                         Sent initrequest.\r
 168                         Connection accepted by v3 target.\r
 169                         ID     : 81/81\r
 170                         Name   : Simple2ZOOM Universal Gateway/GFS/YAZ\r
 171                         Version: 1.03/1.128/3.0.34\r
 172                         Options: search present delSet triggerResourceCtrl scan sort namedResultSets\r
 173                         Elapsed: 0.010718\r
 174                         Z&gt; format marcxml\r
 175                         Z&gt; find <quote>dc.title=zone and dc.author=king</quote>\r
 176                         Sent searchRequest.\r
 177                         Received SearchResponse.\r
 178                         Search was a success.\r
 179                         Number of hits: 0, setno 4\r
 180                         records returned: 0\r
 181                         Elapsed: 0.611432\r
 182                         Z&gt; find <quote>dead zone</quote>\r
 183                         Sent searchRequest.\r
 184                         Received SearchResponse.\r
 185                         Search was a success.\r
 186                         Number of hits: 4, setno 5\r
 187                         records returned: 0\r
 188                         Elapsed: 1.555461\r
 189                         Z&gt; show 1\r
 190                         Sent presentRequest (1+1).\r
 191                         Records: 1\r
 192                         []Record type: XML\r
 193                         &lt;record xmlns:... (rest of record deliberately truncated)\r
 194                         </screen>\r
 195         </section>\r
 196 </chapter>\r
 197 \r