-<!-- $Id: introduction.xml,v 1.4 2001-10-24 09:27:59 adam Exp $ -->
+<!-- $Id: introduction.xml,v 1.8 2002-08-17 07:55:51 adam Exp $ -->
<chapter id="introduction"><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:
+ 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/SR
+ <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
</itemizedlist>
The &asn; module represents the ASN.1 definition of
- the SR/Z39.50 protocol. It establishes a set of type and
+ 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
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
+ 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, 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
+ 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
- <synopsis>
- int z_xxx(ODR o, Z_xxx **p, int optional, const char *name);
- </synopsis>
+ <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>
(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 remainder of the connection's lifetime, you don't have
+ 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/SR
+ 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>
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;.
+ event-processing structure, in a way that is incompatible with
+ the &comstack; interface or some other part of &yaz;.
</para>
</chapter>
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:"yaz.xml"
- sgml-local-catalogs: "../../docbook/docbook.cat"
+ sgml-local-catalogs: nil
sgml-namecase-general:t
End:
-->
projects / yaz-moved-to-github.git / blobdiff