-<!-- $Id: book.xml,v 1.25 2006-04-27 16:17:16 mike Exp $ -->
+<!-- $Id: book.xml,v 1.30 2006-05-03 14:56:07 mike Exp $ -->
<bookinfo>
<title>Metaproxy - User's Guide and Reference</title>
<author>
for more information.
</para>
<para>
- We have succesfully used Metaproxy with Boost using the compilers
+ We have succesfully built Metaproxy using the compilers
<ulink url="&url.gcc;">GCC</ulink> version 4.0 and
<ulink url="&url.vstudio;">Microsoft Visual Studio</ulink> 2003/2005.
</para>
</section>
<section id="installation.debian">
- <title>Installation on Debian</title>
+ <title>Installation on Debian GNU/Linux</title>
<para>
- ### To be written
+ All dependencies for Metaproxy are available as
+ <ulink url="&url.debian;">Debian</ulink>
+ packages for the sarge (stable in 2005) and etch (testing in 2005)
+ distributions.
</para>
<para>
- (Of course, since Debian is a Unix system, the instructions in the
- previous section can be used.)
+ The procedures for Debian based systems, such as
+ <ulink url="&url.ubuntu;">Ubuntu</ulink> is probably similar
</para>
- </section>
+ <para>
+ There is currently no official Debian package for YAZ++.
+ And the Debian package for YAZ is probably too old.
+ Update the <filename>/etc/apt/sources.list</filename>
+ to include the Index Data repository.
+ See YAZ' <ulink url="&url.yaz.download.debian;">Download Debian</ulink>
+ for more information.
+ </para>
+ <screen>
+ apt-get install libxslt1-dev
+ apt-get install libyazpp-dev
+ apt-get install libboost-dev
+ apt-get install libboost-thread-dev
+ apt-get install libboost-date-time-dev
+ apt-get install libboost-program-options-dev
+ apt-get install libboost-test-dev
+ </screen>
+ <para>
+ With these packages installed, the usual configure + make
+ procedure can be used for Metaproxy as outlined in
+ <xref linkend="installation.unix"/>.
+ </para>
+ </section>
<section id="installation.windows">
<title>Installation on Windows</title>
<para>
- Compilation of Metaproxy can be done using
- Microsoft <ulink url="&url.vstudio;">Visual Studio</ulink>.
- We know Version 2003 works. We expect Version 2005 to
- work as well.
+ Metaproxy can be compiled with Microsoft
+ <ulink url="&url.vstudio;">Visual Studio</ulink>.
+ Version 2003 (C 7.1) and 2005 (C 8.0) is known to work.
</para>
<section id="installation.windows.boost">
<title>Boost</title>
<para>
Get Boost from its <ulink url="&url.boost;">home page</ulink>.
You also need Boost Jam (an alternative to make).
- That's also available from this
- home page. The files download are called something like:
- <literal>boost_1_33-1.exe</literal>
+ That's also available from the Boost home page.
+ The files to be downloaded are called something like:
+ <filename>boost_1_33-1.exe</filename>
and
- <literal>boost-jam-3.1.12-1-ntx86.zip</literal>.
- Unpack Boost Jam first. Put <literal>bjam.exe</literal>
+ <filename>boost-jam-3.1.12-1-ntx86.zip</filename>.
+ Unpack Boost Jam first. Put <filename>bjam.exe</filename>
in your system path. Make a command prompt and ensure
it can be found automatically. If not check the PATH.
The Boost .exe is a self-extracting exe with
complete source for Boost. Compile that source with
Boost Jam (An alternative to Make).
The compilation takes a while.
- By default, the Boost build process puts the resulting
+ For Visual Studio 2003, use
+ <screen>
+ bjam "-sTOOLS=vc-7_1"
+ </screen>
+ Here <literal>vc-7_1</literal> refers to a "Toolset" (compiler system).
+ For Visual Studio 2005, use
+ <screen>
+ bjam "-sTOOLS=vc-8_0"
+ </screen>
+ To install the libraries in a common place, use
+ <screen>
+ bjam "-sTOOLS=vc-7_1" install
+ </screen>
+ (or vc-8_0 for VS 2005).
+ </para>
+ <para>
+ By default, the Boost build process installs the resulting
libraries + header files in
<literal>\boost\lib</literal>, <literal>\boost\include</literal>.
</para>
to point to the proper locations of Boost, Libxslt, Libxml2,
zlib, iconv, yaz and yazpp.
</para>
+
+ <variablelist>
+ <varlistentry><term><literal>DEBUG</literal></term>
+ <listitem><para>
+ If set to 1, the software is
+ compiled with debugging libraries (code generation is
+ multi-threaded debug DLL).
+ If set to 0, the software is compiled with release libraries
+ (code generation is multi-threaded DLL).
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>BOOST</literal></term>
+ <listitem>
+ <para>
+ Boost install location
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>BOOST_VERSION</literal></term>
+ <listitem>
+ <para>
+ Boost version (replace . with _).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>BOOST_TOOLSET</literal></term>
+ <listitem>
+ <para>
+ Boost toolset.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>LIBXSLT_DIR</literal>,
+ <literal>LIBXML2_DIR</literal> ..</term>
+ <listitem>
+ <para>
+ Specify the locations of Libxslt, libiconv, libxml2 and
+ libxslt.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
<para>
After succesful compilation you'll find
<literal>metaproxy.exe</literal> in the
</para>
</section>
+
</section>
</chapter>
>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
through it.
</para>
<para>
- ### Describe the use of multiple <literal>VAL_PROXY</literal>
- otherInfos, added by <literal>virt_db</literal> and used by
- <literal>multi</literal>.
+ It is possible for a <literal>virt_db</literal> filter to contain
+ multiple
+ <literal><target></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
+ DB filter is dumb, and does exactly what it's told - no more, no
+ less.
+ 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
+ in it, or (better) fail with an error message.
+ </para>
+ <para>
+ 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
+ <literal>VAL_PROXY</literal>. Each of these new copies is then
+ 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
+ eventually makes it back to the client.
</para>
</section>
<simpara>
<inlinemediaobject>
<imageobject>
- <imagedata fileref="multi.pdf" format="PDF"/>
+ <imagedata fileref="multi.pdf" format="PDF" scale="50"/>
</imageobject>
<imageobject>
<imagedata fileref="multi.png" format="PNG"/>