Make symlink when srcdir=dstdir

[metaproxy-moved-to-github.git] / doc / book.xml

diff --git a/doc/book.xml b/doc/book.xml
index 3faf161..44025aa 100644 (file)
--- a/doc/book.xml
+++ b/doc/book.xml
@@ -1,4 +1,4 @@
-<!-- $Id: book.xml,v 1.29 2006-05-03 13:33:22 mike Exp $ -->
+<!-- $Id: book.xml,v 1.32 2006-05-16 10:34:48 mike Exp $ -->
  <bookinfo>
   <title>Metaproxy - User's Guide and Reference</title>
   <author>
@@ -1184,6 +1184,27 @@ Z>
     be metasearched in this way: issues of resource usage and
     administrative complexity dictate the practical limits.
    </para>
+   <para>
+    What happens when one of the databases doesn't respond?  By default,
+    the entire multi-database search fails, and the appropriate
+    diagnostic is returned to the client.  This is usually appropriate
+    during development, when technicians need maximum information, but
+    can be inconvenient in deployment, when users typically don't want
+    to be bothered with problems of this kind and prefer just to get
+    the records from the databases that are available.  To obtain this
+    latter behaviour add an empty
+    <literal>&lt;hideunavailable&gt;</literal>
+    element inside the
+    <literal>multi</literal> filter:
+   </para>
+   <screen><![CDATA[      <filter type="multi">
+        <hideunavailable/>
+      </filter>]]></screen>
+   <para>
+    Under this regime, an error is reported to the client only if
+    <emphasis>all</emphasis> the databases in a multi-database search
+    are unavailable.
+   </para>
   </section>
 
 
@@ -1221,15 +1242,18 @@ Z>
           >the HTTP 1.1 specification</ulink>.
    </para>
    <para>
-    The role of the <literal>virt_db</literal> filter is to rewrite
-    this otherInfo packet dependent on the virtual database that the
-    client wants to search.  
+    Within Metaproxy, Search requests that are part of the same
+    session as an Init request that carries a
+    <literal>VAL_PROXY</literal> otherInfo are also annotated with the
+    same information.  The role of the <literal>virt_db</literal>
+    filter is to rewrite this otherInfo packet dependent on the
+    virtual database that the client wants to search.
    </para>
    <para>
     When Metaproxy receives a Z39.50 Init request from a client, it
     doesn't immediately forward that request to the back-end server.
     Why not?  Because it doesn't know <emphasis>which</emphasis>
-    back-end server to forward it to until the client sends a search
+    back-end server to forward it to until the client sends a Search
     request that specifies the database that it wants to search in.
     Instead, it just treasures the Init request up in its heart; and,
     later, the first time the client does a search on one of the
@@ -1259,12 +1283,10 @@ Z>
     <literal>&lt;target&gt;</literal>
     elements.  What does this mean?  Only that the filter will add
     multiple <literal>VAL_PROXY</literal> otherInfo packets to the
-    search requests that pass through it.  That's because the virtual
+    Search requests that pass through it.  That's because the virtual
     DB filter is dumb, and does exactly what it's told - no more, no
     less.
-   </para>
-   <para>
-    If a search request with multiple <literal>VAL_PROXY</literal>
+    If a Search request with multiple <literal>VAL_PROXY</literal>
     otherInfo packets reaches a <literal>z3950_client</literal>
     filter, this is an error.  That filter doesn't know how to deal
     with multiple targets, so it will either just pick one and search
@@ -1274,16 +1296,16 @@ Z>
     The <literal>multi</literal> filter comes to the rescue!  This is
     the only filter that knows how to deal with multiple
     <literal>VAL_PROXY</literal> otherInfo packets, and it does so by
-    making multiple copies of the entire search-request: one for each
+    making multiple copies of the entire Search request: one for each
     <literal>VAL_PROXY</literal>.  Each of these new copies is then
-    passed down through the remaining filters in the route, instead of
-    the original one.  (The copies are handled in parallel though the
-    spawning of new threads.)  Since the copies each have ony one
+    passed down through the remaining filters in the route.  (The
+    copies are handled in parallel though the
+    spawning of new threads.)  Since the copies each have only one
     <literal>VAL_PROXY</literal> otherInfo, they can be handled by the
     <literal>z3950_client</literal> filter, which happily deals with
     each one individually.  When the results of the individual
     searches come back up to the <literal>multi</literal> filter, it
-    merges them into a single search-response, which is what
+    merges them into a single Search response, which is what
     eventually makes it back to the client.
    </para>
   </section>