-<!-- $Header: /home/cvsroot/yaz/doc/introduction.xml,v 1.1 2001-01-04 13:36:24 adam Exp $ -->
-<chapter><title>Introduction</title>
+<!-- $Id: introduction.xml,v 1.2 2001-07-19 23:29:40 adam Exp $ -->
+ <chapter><title>Introduction</title>
+
+ <para>
+ The &yaz; toolkit offers several different levels of access to the
+ Z39.50 and SR protocols. The level that you need to use depends on
+ your requirements, and the role (server or client) that you
+ want to implement.
+ </para><para>
+ The basic level, which is independent of the role, consists of three
+ primary interfaces:
+
+ <itemizedlist>
+ <listitem><para>&asn;, which provides a C representation of the Z39.50/SR
+ 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 SR/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
-<para>
-The &yaz; toolkit offers several different levels of access to the
-Z39.50 and SR protocols. The level that you need to use depends on
-your requirements, and the role (server or client) that you
-want to implement.
-</para><para>
-The basic level, which is independent of the role, consists of three
-primary interfaces:
+ <synopsis>
+ int z_xxx(ODR o, Z_xxx **p, int optional, const char *name);
+ </synopsis>
+ (note the lower-case "z" in the function name)
+ </para>
-<itemizedlist>
-<listitem><para>&asn;, which provides a C representation of the Z39.50/SR
-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>
+ <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 section
+ <link linkend="odr-use">Using ODR</link>.
+ </para>
+ </note>
-The &asn; module represents the ASN.1 definition of
-the SR/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
+ <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>
-<synopsis>
-int z_xxx(ODR o, Z_xxx **p, int optional, const char *name);
-</synopsis>
-(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 section
-<link linkend="odr-use">Using ODR</link>.
-</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 (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
+ <!-- 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: "../../docbook/docbook.cat"
+ sgml-namecase-general:t
+ End:
+ -->
projects / yaz-moved-to-github.git / blobdiff