-<para>
-When you have created a BER-encoded buffer, you can use the &comstack;
-subsystem to transmit (or receive) data over the network. The &comstack;
-module provides simple functions for establishing a connection
-(passively or actively, depending on the role of your application),
-and for exchanging BER-encoded PDUs over that connection. When you
-create a connection endpoint, you need to specify what transport to
-use (OSI or TCP/IP), and which protocol you want to use (SR or
-Z39.50). For the remainer of the connection's lifetime, you don't have
-to worry about the underlying transport protocol at all - the &comstack;
-will ensure that the correct mechanism is used.
-</para>
-<para>
-We call the combined interfaces to &odr;, &asn;, and &comstack; the service
-level API. It's the API that most closely models the Z39.50/SR
-service/protocol definition, and it provides unlimited access to all
-fields and facilities of the protocol definitions.
-</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 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
-transparent transport approach of the &comstack; module. Secondly,
-we realise that you may have to fit the toolkit into an existing
-event-processing structure, in a way that
-is incompatible with the &comstack; interface or some other part of &yaz;.
-</para>
-</chapter>
\ No newline at end of file
+ <listitem>
+ <para>
+ <xref linkend="asn"/> documents the most commonly used Z39.50
+ C data structures offered by the &yaz; API. Client
+ developers using ZOOM and non-Z39.50 implementors may skip this.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <xref linkend="soap"/> describes how SRW and SOAP is used
+ in &yaz;. Only if you're developing SOAP/SRW applications
+ this section is a must.
+ </para>
+ </listitem>
+
+ <listitem>
+ <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/SRU implementors
+ might find the <link linkend="tools.cql">CQL</link> section
+ particularly useful.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <xref linkend="odr"/> goes through the details of the
+ ODR module which is the work horse that encodes and decodes
+ BER packages. Implementors using ZOOM only, do <emphasis>not</emphasis>
+ need reading this.
+ Most other Z39.50 implementors only need to read the first two
+ sections (<xref linkend="odr.introduction"/> and
+ <xref linkend="odr.use"/>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <xref linkend="comstack"/> describes the network layer module
+ COMSTACK. Implementors using ZOOM or the generic frontend server
+ may skip this. Others, presumably, handling client/server
+ communication on their own should read this.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </sect1>
+ <sect1 id="introduction.api"><title>The API</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>,
+ <ulink url="http://www.nlc-bnc.ca/iso/ill/">ILL</ulink> and
+ <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.
+ 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 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>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
+ 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>z-core.h</filename> (for the types
+ from the protocol), <filename>odr.h</filename> (for the primitive ASN.1
+ 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
+
+ <funcsynopsis>
+ <funcprototype><funcdef>int <function>z_<replaceable>xxx</replaceable></function></funcdef>
+ <paramdef>ODR <parameter>o</parameter></paramdef>
+ <paramdef>Z_<replaceable>xxx</replaceable> **<parameter>p</parameter></paramdef>
+ <paramdef>int <parameter>optional</parameter></paramdef>
+ <paramdef>const char *<parameter>name</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ (note the lower-case "z" in the function name)
+ </para>
+
+ <note>
+ <para>
+ If you are using the premade definitions of the &asn; module, and you
+ are not adding new protocol of your own, the only parts of &odr; that you
+ need to worry about are documented in
+ <xref linkend="odr.use"/>.
+ </para>
+ </note>
+
+ <para>
+ When you have created a BER-encoded buffer, you can use the &comstack;
+ subsystem to transmit (or receive) data over the network. The &comstack;
+ module provides simple functions for establishing a connection
+ (passively or actively, depending on the role of your application),
+ and for exchanging BER-encoded PDUs over that connection. When you
+ 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;
+ will ensure that the correct mechanism is used.
+ </para>
+ <para>
+ We call the combined interfaces to &odr;, &asn;, and &comstack; the service
+ level API. It's the API that most closely models the Z39.50
+ service/protocol definition, and it provides unlimited access to all
+ fields and facilities of the protocol definitions.
+ </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
+ 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
+ transparent transport approach of the &comstack; module. Secondly,
+ we realize that you may have to fit the toolkit into an existing
+ event-processing structure, in a way that is incompatible with
+ the &comstack; interface or some other part of &yaz;.
+ </para>
+ </sect1>
+ </chapter>
+
+ <!-- Keep this comment at the end of the file
+ Local variables:
+ mode: sgml
+ sgml-omittag:t
+ sgml-shorttag:t
+ sgml-minimize-attributes:nil
+ sgml-always-quote-attributes:t
+ sgml-indent-step:1
+ sgml-indent-data:t
+ sgml-parent-document:"yaz.xml"
+ sgml-local-catalogs: nil
+ sgml-namecase-general:t
+ End:
+ -->