Introduction
&yaz; is a C/C++ library for information retrieval applications
using the Z39.50/SRU/Solr protocols for information retrieval.
Properties of &yaz;:
Complete
Z39.50 version 3 support.
Amendments and Z39.50-2002 revision is supported.
Supports
SRU GET/POST/SOAP
version 1.1, 1.2 and 2.0 (over HTTP and HTTPS).
Includes BER encoders/decoders for the
ISO ILL
protocol.
Supports
Solr Web Service version 1.4.x
(client side only)
Supports the following transports: BER over TCP/IP
(RFC1729),
BER over unix local socket, and
HTTP 1.1.
Secure Socket Layer support using
GnuTLS.
If enabled, &yaz; uses HTTPS transport (for SOAP) or
"Secure BER" (for Z39.50).
Offers
ZOOM C API implementing
Z39.50, SRU and Solr Web Service.
The &yaz; library offers a set of useful utilities
related to the protocols, such as MARC (ISO2709) parser,
CCL (ISO8777) parser,
CQL
parser, memory management routines, character set conversion.
Portable code. &yaz; compiles out-of-the box on most Unixes and
on Windows using Microsoft Visual C++.
Fast operation. The C based BER encoders/decoders as well
as the server component of &yaz; is very fast.
Liberal license that allows for commercial use of &yaz;.
Reading this ManualMost implementors only need to read a fraction of the
material in thie manual, so a quick walkthrough of the chapters
is in order.
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 your application link
with &yaz;.
describes the ZOOM API of &yaz;.
This is definitely worth a read if you wish to develop a Z39.50/SRU
client.
describes the generic frontend server
and explains how to develop server Z39.50/SRU applications for &yaz;.
Obviously worth reading if you're to develop a server.
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.
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.
describes how SRU and SOAP is used
in &yaz;. Only if you're developing SRU applications
this section is a must.
contains sections for the various
tools offered by &yaz;. Scan through the material quickly
and see what's relevant to you! SRU implementors
might find the CQL section
particularly useful.
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 ( and
).
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.
The API
The &yaz;
toolkit offers several different levels of access to the
ISO23950/Z39.50,
ILL and
SRU
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
ZOOM API.
It is, by far, the easiest way to develop clients in C.
Server implementers should consider the
generic frontend server.
None of those high-level APIs support the whole protocol, but
they do include most facilities used in existing Z39.50 applications.
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;.
The YAZ toolkit modules is shown in figure .
There are four layers.
A client or server application (or both).
This layer includes ZOOM and the generic frontend server.
The second layer provides a C represenation of the
protocol units (packages) for Z39.50 ASN.1, ILL ASN.1,
SRU.
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.
The lowest layer is &comstack; which exchanges the encoded packages
with a peer process over a network.
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.
&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 Z_, 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
Odr_ is sometimes seen. Either way, look for
the actual definition in either z-core.h (for the types
from the protocol), odr.h (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
int z_xxxODR oZ_xxx **pint optionalconst char *name
(note the lower-case "z" in the function name)
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
.
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.
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.
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;.