-<!-- $Id: introduction.xml,v 1.8 2002-08-17 07:55:51 adam Exp $ -->
+<!-- $Id: introduction.xml,v 1.9 2003-02-21 00:24:26 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;.
+ &yaz; is a C/C++ library for information retrieval applications
+ using the Z39.50/SRW protocols for information retrieval.
</para>
+
<para>
- The basic low level modules, which are independent of the role
- (client or server), consist of three primary interfaces:
-
+ Properties of &yaz;:
<itemizedlist>
- <listitem><para>&asn;, which provides a C representation of the Z39.50
- protocol packages (PDUs).
+ <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.
+ </para></listitem>
+ <listitem><para>
+ Supports
+ <ulink url="http://www.loc.gov/z3950/agency/zing/srw/">SRW</ulink>
+ version 1.0 (over HTTP and HTTPS).
+ </para></listitem>
+ <listitem><para>
+ Includes BER encoders/decoders for the
+ <ulink url="http://www.nlc-bnc.ca/iso/ill/">ISO ILL</ulink>
+ protocol.
+ </para></listitem>
+ <listitem><para>
+ Supports the following transports: BER over TCP/IP
+ (<ulink url="http://www.faqs.org/rfcs/rfc1729.html">RFC1729</ulink>),
+ BER over unix local socket, and
+ <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616.html">HTTP
+ 1.1</ulink>.
+ </para></listitem>
+ <listitem><para>
+ Secure Socket Layer support using
+ <ulink url="http://www.openssl.org/">OpenSSL</ulink>.
+ If enabled, &yaz; uses HTTPS transport (for SOAP) or
+ "Secure BER" (for Z39.50).
+ </para></listitem>
+ <listitem><para>
+ Offers
+ <ulink url="http://zoom.z3950.org/">ZOOM</ulink>
+ C API implementing both Z39.50 and SRW.
</para></listitem>
- <listitem><para>&odr;, which encodes and decodes the packages according
- to the BER specification.
+ <listitem><para>
+ The &yaz; library offers a set of useful utilities
+ related to the protocols, such as MARC (ISO2709) parser,
+ CCL (ISO8777) parser,
+ <ulink url="http://www.loc.gov/z3950/agency/zing/cql/">CQL</ulink>
+ parser, memory management routines, character set conversion.
</para></listitem>
- <listitem><para>&comstack;, which exchanges the encoded packages with
- a peer process over a network.
+ <listitem><para>
+ Portable code. &yaz; compiles out-of-the box on most Unixes and
+ on Windows using Microsoft Visual C++.
+ </para></listitem>
+ <listitem><para>
+ Liberal license that allows for commercial use of &yaz;.
</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>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>
+ <sect1 id="introduction.reading"><title>Reading this Manual</title>
+ <para>Most implementors only need to read a fraction of the
+ material in thie manual, so a quick walkthrough of the chapters
+ is in order.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <xref linkend="installation"/> contains installation
+ instructions for &yaz;. You don't need reading this
+ if you expect to download &yaz; binaries.
+ However, the chapter contains information about how
+ to make <emphasis>your</emphasis> application link
+ with &yaz;.
+ </para>
+ </listitem>
+
+ <listitem>
+ <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
+ and explains how to develop server Z39.50/SRW applications for &yaz;.
+ Obviously worth reading if you're to develop a server.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <xref linkend="client"/> describes how to use the &yaz; Z39.50
+ client. If you're developer and wish to test your server
+ or a server from another party, you might find this chapter
+ useful.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <xref linkend="asn"/> documents the most commonly used Z39.50
+ C data structures offered by the &yaz; API. Client
+ developers using ZOOM you do not need reading this.
+ For the remaining client developers (not using ZOOM),
+ reading this chapter is a must.
+ Z39.50 server implementors should read this, unless you're
+ developing a simple server (or SRW only).
+ </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 implementors
+ might find the <link linkend="tools.cql">CQL</link> section
+ particularly useful.
+ </para>
+ </listitem>
- <note>
+ <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 not need reading this.
+ Most other Z39.50 implementors only need to read the first two
+ sections <link linkend="odr.introduction">Introduction</link>,
+ <link linkend="odr.use">Using ODR</link>.
+ </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>
- 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>.
+ 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
+ SRW 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>
- </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.
+ 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>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 section
+ <link linkend="odr-use">Using ODR</link>.
+ </para>
+ </note>
+
<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
+ 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
+ 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>
+ 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
-<!-- $Id: zoom.xml,v 1.21 2002-12-09 23:32:29 adam Exp $ -->
- <chapter id="zoom"><title>Building clients with ZOOM</title>
+<!-- $Id: zoom.xml,v 1.22 2003-02-21 00:24:26 adam Exp $ -->
+ <chapter id="zoom"><title>ZOOM</title>
<para>
&zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is
an initiative started by Mike Taylor (Mike is from the UK, which
provide a common Z39.50 client API not bound to a particular
programming language or toolkit.
</para>
+
+ <note>
+ <para>
+ A recent addition to &yaz; is SRW support. You can now make
+ SRW ZOOM connections by specifying a new scheme for the
+ host name for a connection.
+ </para>
+ </note>
+
<para>
The lack of a simple Z39.50 client API for &yaz; has become more
and more apparent over time. So when the first &zoom; specification
slash, the following part specifies a database for the connection.
</para>
<para>
+ You can prefix the host with a scheme followed by colon. The
+ default scheme is <literal>tcp</literal> (Z39.50 protocol).
+ The scheme <literal>http</literal> selects SRW over HTTP.
+ </para>
+ <para>
Connection objects should be destroyed using the function
<function>ZOOM_connection_destroy</function>.
</para>
of <function>ZOOM_connection_error</function> that is capable of
returning name of diagnostic set in <parameter>dset</parameter>.
</para>
- <sect2><title>Protocol behavior</title>
+ <sect2><title>Z39.50 Protocol behavior</title>
<para>
The calls <function>ZOOM_connection_new</function> and
<function>ZOOM_connection_connect</function> establishes a TCP/IP
API cannot tell the outcome (yet).
</para>
</sect2>
+ <sect2><title>SRW Protocol behavior</title>
+ <para>
+ The SRW protocol doesn't feature an Init Request, so
+ the connection phase merely establishes a TCP/IP connection
+ with the SOAP service.
+ </para>
+ <para>None of the ZOOM connection options
+ affect SRW and they are ignored. However, future versions
+ of &yaz; might honor <literal>implementationName</literal> and
+ put that as part of User-Agent header for HTTP requests.
+ The <literal>charset</literal>, and <literal>lang</literal>
+ might also affect HTTP headers in future releases.
+ </para>
+ </sect2>
</sect1>
<sect1 id="zoom.query"><title>Queries</title>
<para>
int ZOOM_query_prefix(ZOOM_query q, const char *str);
+ int ZOOM_query_cql(ZOOM_query s, const char *str);
+
int ZOOM_query_sortby(ZOOM_query q, const char *criteria);
</synopsis>
<para>
and destroy them by calling <function>ZOOM_query_destroy</function>.
RPN-queries can be specified in <link linkend="PQF">PQF</link>
notation by using the
- function <function>ZOOM_query_prefix</function>. More
- query types will be added later, such as
+ function <function>ZOOM_query_prefix</function>.
+ The <function>ZOOM_query_cql</function> specifies a CQL
+ query to be sent to the server/target.
+ More query types will be added in future versions of &yaz;, such as
<link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
etc. In addition to a search, a sort criteria may be set. Function
<function>ZOOM_query_sortby</function> specifies a
</tgroup>
</table>
<sect2>
- <title>Protocol behavior</title>
+ <title>Z39.50 Protocol behavior</title>
<para>
The creation of a result set involves at least a SearchRequest
- SearchResponse protocol handshake. Following that, if a sort
to specify one elementSetName option rather than three.
</para>
</sect2>
+ <sect2>
+ <title>SRW Protocol behavior</title>
+ <para>
+ Current version of &yaz; does not take advantage of a result set id
+ returned by the SRW server. Future versions might do, however.
+ Since, the ZOOM driver does not save result set IDs any
+ present (retrieval) is transformed to a SRW SearchRetrieveRequest
+ with same query but, possibly, different offsets.
+ </para>
+ <para>
+ Option <literal>schema</literal> specifies SRW schema
+ for retrieval. However, options <literal>elementSetName</literal> and
+ <literal>preferredRecordSyntax</literal> are ignored.
+ </para>
+ <para>
+ Options <literal>start</literal> and <literal>count</literal>
+ are supported by SRW.
+ The remaining options
+ <literal>piggyback</literal>,
+ <literal>smallSetUpperBound</literal>,
+ <literal>largeSetLowerBound</literal>,
+ <literal>mediumSetPresentNumber</literal>,
+ <literal>mediumSetElementSetName</literal>,
+ <literal>smallSetElementSetName</literal> are
+ unsupported.
+ </para>
+ <para>
+ SRW supports CQL queries, <emphasis>not</emphasis> PQF.
+ If PQF is used, however, the PQF query is transferred anyway
+ using non-standard element <literal>pQuery</literal> in
+ SRW SearchRetrieveRequest.
+ </para>
+ <para>
+ Unfortunately, SRW does not define a database setting. Hence,
+ <literal>databaseName</literal> is unsupported and ignored.
+ However, the path part in host parameter for functions
+ <function>ZOOM_connecton_new</function> and
+ <function>ZOOM_connection_connect</function> acts as a
+ database (at least for the &yaz; SRW server).
+ </para>
+ </sect2>
</sect1>
<sect1 id="zoom.records"><title>Records</title>
<para>
</varlistentry>
</variablelist>
</para>
- <sect2><title>Protocol behavior</title>
+ <sect2><title>Z39.50 Protocol behavior</title>
<para>
The functions <function>ZOOM_resultset_record</function> and
<function>ZOOM_resultset_records</function> inspects the client-side
<emphasis>now</emphasis>.
</para>
</sect2>
+ <sect2><title>SRW Protocol behavior</title>
+ <para>
+ The ZOOM driver for SRW treats records returned by a SRW server
+ as if they where Z39.50 records with transfer syntax XML and
+ no element set name or database name.
+ </para>
+ </sect2>
</sect1>
<sect1 id="zoom.scan"><title>Scan</title>
<para>
is the <literal>ZOOM_scanset</literal> which is a set of terms
returned by a target.
</para>
+
+ <para>
+ The Scan interface is Z39.50 only. SRW version 1.0 does not
+ support this.
+ </para>
+
<synopsis>
ZOOM_scanset ZOOM_connection_scan (ZOOM_connection c,
const char *startterm);
projects / yaz-moved-to-github.git / commitdiff