-<!-- $Id: introduction.xml,v 1.10 2003-02-21 12:06:05 adam Exp $ -->
+<!-- $Id: introduction.xml,v 1.14 2003-04-28 21:02:16 adam Exp $ -->
<chapter id="introduction"><title>Introduction</title>
<para>
&yaz; is a C/C++ library for information retrieval applications
- using the Z39.50/SRW protocols for information retrieval.
+ using the Z39.50/SRW/SRU protocols for information retrieval.
</para>
<para>
Properties of &yaz;:
<itemizedlist>
<listitem><para>
- Fast operation. The C based BER encoders/decoders as well
- as the server component of &yaz; is very fast.
- </para></listitem>
- <listitem><para>
Complete
<ulink url="http://www.loc.gov/z3950/agency/">Z39.50</ulink>
- version 3 support. All newer extensions
- including Z39.50-2000 have been incorporated.
+ version 3 support. Amendments and Z39.50-2002 revision is
+ supported.
</para></listitem>
<listitem><para>
Supports
- <ulink url="http://www.loc.gov/z3950/agency/zing/srw/">SRW</ulink>
+ <ulink url="http://www.loc.gov/z3950/agency/zing/srw/">SRW/SRU</ulink>
version 1.0 (over HTTP and HTTPS).
</para></listitem>
<listitem><para>
on Windows using Microsoft Visual C++.
</para></listitem>
<listitem><para>
+ Fast operation. The C based BER encoders/decoders as well
+ as the server component of &yaz; is very fast.
+ </para></listitem>
+ <listitem><para>
Liberal license that allows for commercial use of &yaz;.
</para></listitem>
</itemizedlist>
</listitem>
<listitem>
- <para>
+ <para>
<xref linkend="zoom"/> describes the ZOOM API of &yaz;.
This is definitely worth a read if you wish to develop a Z39.50/SRW
client.
</para>
</listitem>
-
+
<listitem>
<para>
- <xref linkend="zoom"/> describes the generic frontend server
+ <xref linkend="server"/> describes the generic frontend server
and explains how to develop server Z39.50/SRW applications for &yaz;.
Obviously worth reading if you're to develop a server.
</para>
<para>
<xref linkend="tools"/> contains sections for the various
tools offered by &yaz;. Scan through the material quickly
- and see what's relevant to you! SRW implementors
+ and see what's relevant to you! SRW/SRU implementors
might find the <link linkend="tools.cql">CQL</link> section
particularly useful.
</para>
toolkit offers several different levels of access to the
<ulink url="http://www.loc.gov/z3950/agency/">ISO23950/Z39.50</ulink>,
<ulink url="http://www.nlc-bnc.ca/iso/ill/">ILL</ulink> and
- SRW protocols.
+ <ulink url="http://www.loc.gov/z3950/agency/zing/srw/">SRW</ulink>
+ protocols.
The level that you need to use depends on your requirements, and
the role (server or client) that you want to implement.
If you're developing a client application you should consider the
<link linkend="zoom">ZOOM</link> API.
- It is, by far, the easiest way to develop clients in C.
+ It is, by far, the easiest way to develop clients in C.
Server implementers should consider the
<link linkend="server">generic frontend server</link>.
None of those high-level APIs support the whole protocol, but
you're going to develop an ILL application you'll have to learn the lower
level APIs of &yaz;.
</para>
- <para>
- The basic low level modules, which are independent of the role
- (client or server), consist of three primary interfaces:
-
+
+
+ <para>
+ The YAZ toolkit modules is shown in figure <xref linkend="yaz.layer"/>.
+ </para>
+ <figure id="yaz.layer">
+ <title>YAZ layers</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="apilayer.png" format="PNG"/>
+ </imageobject>
+ <imageobject>
+ <imagedata fileref="apilayer.eps" format="EPS"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>
+ There are four layers.
<itemizedlist>
- <listitem><para>&asn;, which provides a C representation of the Z39.50
- protocol packages (PDUs).
- </para></listitem>
- <listitem><para>&odr;, which encodes and decodes the packages according
- to the BER specification.
- </para></listitem>
- <listitem><para>&comstack;, which exchanges the encoded packages with
- a peer process over a network.
- </para></listitem>
+ <listitem>
+ <para>A client or server application (or both).
+ This layer includes ZOOM and the generic frontend server.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The second layer provides a C represenation of the
+ protocol units (packages) for Z39.50 ASN.1, ILL ASN.1,
+ SRW SOAP.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The third layer encodes and decodes protocol data units to
+ simple packages (buffer with certain length). The &odr; module
+ encodes and decodes BER whereas the HTTP modules encodes and
+ decodes HTTP ruquests/responses.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The lowest layer is &comstack; which exchanges the encoded packages
+ with a peer process over a network.
+ </para>
+ </listitem>
</itemizedlist>
-
+ </para>
+ <para>
The &asn; module represents the ASN.1 definition of
the Z39.50 protocol. It establishes a set of type and
structure definitions, with one structure for each of the top-level
create a connection endpoint, you need to specify what transport to
use (TCP/IP, SSL or UNIX sockets).
For the remainder of the connection's lifetime, you don't have
- to worry about the underlying transport protocol at all - the &comstack;
+ to worry about the underlying transport protocol at all - the &comstack;
will ensure that the correct mechanism is used.
</para>
<para>
</para>
<para>
The reason that the &yaz; service-level API is a conglomerate of the
- APIs from three different submodules is twofold. First, we wanted to allow
+ APIs from three different submodules is twofold. First, we wanted to allow
the user a choice of different options for each major task. For instance,
if you don't like the protocol API provided by &odr;/&asn;, you
can use SNACC or BERUtils instead, and still have the benefits of the
projects / yaz-moved-to-github.git / blobdiff