# Introduction

&yaz; is a C/C++ library for information retrieval applications using the Z39.50/SRW/SRU protocols for information retrieval.

Properties of &yaz;:

- Complete Z39.50 version 3 support. Amendments and Z39.50-2002 revision is supported.

- Supports SRW/SRU version 1.0 (over HTTP and HTTPS).

- Includes BER encoders/decoders for the ISO ILL protocol.

- Supports the following transports: BER over TCP/IP (RFC1729), BER over unix local socket, and HTTP 1.1.

- Secure Socket Layer support using OpenSSL. If enabled, &yaz; uses HTTPS transport (for SOAP) or "Secure BER" (for Z39.50).

- Offers ZOOM C API implementing both Z39.50 and SRW.

- 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 Manual

Most 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/SRW client.

- 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.

- 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 SRW and SOAP is used in &yaz;. Only if you're developing SOAP/SRW 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! SRW/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 Introduction, Using ODR.

- 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 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 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 .

### YAZ layers

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, SRW SOAP.

- 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_xxx
          ODR o
          Z_xxx **p
          int optional
          const 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 section Using ODR.

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;.