+<!-- $Id: introduction.xml,v 1.7 2001-10-26 20:13:44 adam Exp $ -->
+ <chapter id="introduction"><title>Introduction</title>
+
+ <para>
+ The <ulink url="http://www.indexdata.dk/yaz/">&yaz;</ulink>
+ toolkit offers several different levels of access to the
+ <ulink url="http://www.loc.gov/z3950/agency/">ISO23950/Z39.50</ulink>
+ and <ulink url="http://www.nlc-bnc.ca/iso/ill/">ILL</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.
+ Server implementers should consider the
+ <link linkend="server">generic frontend server</link>.
+ None of those high-level APIs support the whole protocol, but
+ they do include most facilities used in existing Z39.50
+ applications.
+ </para>
+ <para>
+ If you're using 'exotic' functionality (meaning anything not included in
+ the high-level APIs), developing non-standard extensions to Z39.50 or 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:
+
+ <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>
+ </itemizedlist>
+
+ 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
+ PDUs, and one structure or type for each of the contained ASN.1 types.
+ For primitive types, or other types that are defined by the ASN.1
+ standard itself (such as the EXTERNAL type), the C representation is
+ provided by the &odr; (Open Data Representation) subsystem.
+ </para>
+ <para>
+ &odr; is a basic mechanism for representing an
+ ASN.1 type in the C programming language, and for implementing BER
+ encoders and decoders for values of that type. The types defined in
+ the &asn; module generally have the prefix <literal>Z_</literal>, and
+ a suffix corresponding to the name of the type in the ASN.1
+ specification of the protocol (generally Z39.50-1995). In the case of
+ base types (those originating in the ASN.1 standard itself), the prefix
+ <literal>Odr_</literal> is sometimes seen. Either way, look for
+ the actual definition in either <filename>proto.h</filename> (for the types
+ from the protocol), <filename>odr.h</filename> (for the primitive ASN.1
+ types, or <filename>odr_use.h</filename> (for the ASN.1
+ <emphasis>useful</emphasis> types). The &asn; library also
+ provides functions (which are, in turn, defined using &odr;
+ primitives) for encoding and decoding data values. Their general form is