X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fadministration.xml;h=42e13c1f724e485b8b9dc30eba0efb839582ddc2;hb=bfd4dd0d44c779d699f7a1b32e72744733f02caf;hp=eee315e1de6912fe8e955d22d33395c59c0bfbea;hpb=b83408311d403f7463c336ec398766ec7d719418;p=idzebra-moved-to-github.git

diff --git a/doc/administration.xml b/doc/administration.xml
index eee315e..42e13c1 100644
--- a/doc/administration.xml
+++ b/doc/administration.xml
@@ -1,5 +1,5 @@
 <chapter id="administration">
- <!-- $Id: administration.xml,v 1.23 2006-02-15 12:08:47 marc Exp $ -->
+ <!-- $Id: administration.xml,v 1.27 2006-03-04 21:39:20 marc Exp $ -->
  <title>Administrating Zebra</title>
  <!-- ### It's a bit daft that this chapter (which describes half of
           the configuration-file formats) is separated from
@@ -1023,6 +1023,236 @@
    
  </sect1>
 
+ <sect1 id="administration-extended-services">
+  <title>Extended Services: Remote Insert, Update and Delete</title>
+  
+  <para>
+    The extended services are not enabled by default in zebra - due to the
+    fact that they modify the system.
+    In order to allow anybody to update, use
+    <screen>
+    perm.anonymous: rw
+    </screen>
+    in the main zebra configuration file <filename>zebra.cfg</filename>.
+    Or, even better, allow only updates for a particular admin user. For
+    user <literal>admin</literal>, you could use:
+    <screen>
+     perm.admin: rw
+     passwd: passwordfile
+    </screen>
+    And in <filename>passwordfile</filename>, specify users and
+    passwords as colon seperated strings:
+    <screen> 
+     admin:secret
+    </screen> 
+   </para>
+   <para>
+    We can now start a yaz-client admin session and create a database:
+   <screen>
+    <![CDATA[
+     $ yaz-client localhost:9999 -u admin/secret
+     Z> adm-create
+     ]]>
+   </screen>
+    Now the <literal>Default</literal> database was created,
+    we can insert an XML file (esdd0006.grs
+    from example/gils/records) and index it:
+   <screen>  
+    <![CDATA[
+     Z> update insert 1 esdd0006.grs
+     ]]>
+   </screen>
+    The 3rd parameter - <literal>1</literal> here -
+      is the opaque record ID from <literal>Ext update</literal>.
+      It a record ID that <emphasis>we</emphasis> assign to the record
+    in question. If we do not 
+    assign one, the usual rules for match apply (recordId: from zebra.cfg).
+   </para>
+   <para>
+    Actually, we should have a way to specify "no opaque record id" for
+    yaz-client's update command.. We'll fix that.
+   </para>
+   <para>
+    The newly inserted record can be searched as usual:
+    <screen>
+    <![CDATA[
+     Z> f utah
+     Sent searchRequest.
+     Received SearchResponse.
+     Search was a success.
+     Number of hits: 1, setno 1
+     SearchResult-1: term=utah cnt=1
+     records returned: 0
+     Elapsed: 0.014179
+     ]]>
+    </screen>
+   </para>
+   <para>
+    Let's delete the beast:
+    <screen>
+    <![CDATA[
+     Z> update delete 1
+     No last record (update ignored)
+     Z> update delete 1 esdd0006.grs
+     Got extended services response
+     Status: done
+     Elapsed: 0.072441
+     Z> f utah
+     Sent searchRequest.
+     Received SearchResponse.
+     Search was a success.
+     Number of hits: 0, setno 2
+     SearchResult-1: term=utah cnt=0
+     records returned: 0
+     Elapsed: 0.013610
+     ]]>
+     </screen>
+    </para>
+    <para>
+    If shadow register is enabled in your
+    <filename>zebra.cfg</filename>,
+    you must run the adm-commit command
+    <screen>
+    <![CDATA[
+     Z> adm-commit
+     ]]>
+    </screen>
+     after each update session in order write your changes from the
+     shadow to the life register space.
+   </para>
+   <para>
+    Extended services are also available from the YAZ client layer. An
+    example of an YAZ-PHP extended service transaction is given here:
+    <screen>
+    <![CDATA[
+     $record = '<record><title>A fine specimen of a record</title></record>';
+
+     $options = array('action' => 'recordInsert',
+                      'syntax' => 'xml',
+                      'record' => $record,
+                      'databaseName' => 'mydatabase'
+                     );
+
+     yaz_es($yaz, 'update', $options);
+     yaz_es($yaz, 'commit', array());
+     yaz_wait();
+
+     if ($error = yaz_error($yaz))
+       echo "$error";
+     ]]>
+    </screen>  
+    The <literal>action</literal> parameter can be any of 
+    <literal>recordInsert</literal> (will fail if the record already exists),
+    <literal>recordReplace</literal> (will fail if the record does not exist),
+    <literal>recordDelete</literal> (will fail if the record does not
+       exist), and
+    <literal>specialUpdate</literal> (will insert or update the record
+       as needed).
+   </para>
+   <para>
+    If a record is inserted
+    using the action  <literal>recordInsert</literal> 
+    one can specify the optional
+    <literal>recordIdOpaque</literal> parameter, which is a
+    client-supplied, opaque record identifier. This identifier will
+    replace zebra's own automagic identifier generation.  
+   </para>
+   <para>
+    When using the action <literal>recordReplace</literal> or
+    <literal>recordDelete</literal>, one must specify the additional 
+    <literal>recordIdNumber</literal> parameter, which must be an
+    existing Zebra internal system ID number. When retrieving existing
+    records, the ID number is returned in the field
+    <literal>/*/id:idzebra/localnumber</literal> in the namespace
+    <literal>xmlns:id="http://www.indexdata.dk/zebra/"</literal>,
+    where it can be picked up for later record updates or deletes. 
+   </para>
+ </sect1>
+
+
+  <sect1 id="gfs-config">
+   <title>YAZ Frontend Virtual Hosts</title>
+    <para>
+     <command>zebrasrv</command> uses the YAZ server frontend and does
+     support multiple virtual servers behind multiple listening sockets.
+    </para>
+    &zebrasrv-virtual;
+ 
+   <para>
+    Section "Virtual Hosts" in the YAZ manual.
+    <filename>http://www.indexdata.dk/yaz/doc/server.vhosts.tkl</filename>
+   </para>
+ </sect1>
+
+
+  <sect1 id="administration-cql-to-pqf">
+   <title>Server Side CQL to PQF Query Translation</title>
+   <para>
+    Using the
+    <literal>&lt;cql2rpn&gt;l2rpn.txt&lt;/cql2rpn&gt;</literal>
+      YAZ Frontend Virtual
+    Hosts option, one can configure
+    the YAZ Frontend CQL-to-PQF
+    converter, specifying the interpretation of various 
+    <ulink url="http://www.loc.gov/standards/sru/cql/">CQL</ulink>
+    indexes, relations, etc. in terms of Type-1 query attributes.
+    <!-- The  yaz-client config file -->  
+   </para>
+   <para>
+    For example, using server-side CQL-to-PQF conversion, one might
+    query a zebra server like this:
+    <screen>
+    <![CDATA[
+     yaz-client localhost:9999
+     Z> querytype cql
+     Z> find text=(plant and soil)
+     ]]>
+    </screen>
+     and - if properly configured - even static relevance ranking can
+     be performed using CQL query syntax:
+    <screen>
+    <![CDATA[
+     Z> find text = /relevant (plant and soil)
+     ]]>
+     </screen>
+   </para>
+
+   <para>
+    By the way, the same configuration can be used to 
+    search using client-side CQL-to-PQF conversion:
+    (the only difference is <literal>querytype cql2rpn</literal> 
+    instead of 
+    <literal>querytype cql</literal>, and the call specifying a local
+    conversion file)
+    <screen>
+    <![CDATA[
+     yaz-client -q local/cql2pqf.txt localhost:9999
+     Z> querytype cql2rpn
+     Z> find text=(plant and soil)
+     ]]>
+     </screen>
+   </para>
+
+   <para>
+    Exhaustive information can be found in the
+    Section "Specification of CQL to RPN mappings" in the YAZ manual.
+    <ulink url="http://www.indexdata.dk/yaz/doc/tools.tkl#tools.cql.map">
+     http://www.indexdata.dk/yaz/doc/tools.tkl#tools.cql.map</ulink>,
+   and shall therefore not be repeated here.
+   </para> 
+  <!-- 
+  <para>
+    See 
+      <ulink url="http://www.loc.gov/z3950/agency/zing/cql/dc-indexes.html">
+      http://www.loc.gov/z3950/agency/zing/cql/dc-indexes.html</ulink>
+    for the Maintenance Agency's work-in-progress mapping of Dublin Core
+    indexes to Attribute Architecture (util, XD and BIB-2)
+    attributes.
+   </para>
+   -->
+ </sect1>
+
+
  
 </chapter>