1 <?xml version="1.0" standalone="no"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
5 <!ENTITY % local SYSTEM "local.ent">
7 <!ENTITY % entities SYSTEM "entities.ent">
9 <!ENTITY % idcommon SYSTEM "common/common.ent">
14 <title>YAZ User's Guide and Reference</title>
16 <author><firstname>Sebastian</firstname><surname>Hammer</surname></author>
17 <author><firstname>Adam</firstname><surname>Dickmeiss</surname></author>
18 <author><firstname>Mike</firstname><surname>Taylor</surname></author>
19 <author><firstname>Heikki</firstname><surname>Levanto</surname></author>
20 <author><firstname>Dennis</firstname><surname>Schafroth</surname></author>
22 <releaseinfo>&version;</releaseinfo>
24 <year>©right-year;</year>
25 <holder>Index Data</holder>
29 This document is the programmer's guide and reference to the &yaz;
30 package version &version;. &yaz; is a compact toolkit that provides
31 access to the Z39.50 and SRU/Solr protocols, as well as a set of
32 higher-level tools for implementing the server and client
34 The documentation can be used on its own, or as a reference when
35 looking at the example applications provided with the package.
40 <imagedata fileref="common/id.png" format="PNG"/>
43 <imagedata fileref="common/id.eps" format="EPS"/>
48 <chapter id="introduction">
49 <title>Introduction</title>
51 &yaz; is a C/C++ library for information retrieval applications
52 using the Z39.50/SRU/Solr protocols for information retrieval.
60 <ulink url="&url.z39.50;">Z39.50</ulink> version 3 support.
61 Amendments and Z39.50-2002 revision is supported.
67 <ulink url="&url.sru;">SRU GET/POST/SOAP</ulink>
68 version 1.1, 1.2 and 2.0 (over HTTP and HTTPS).
73 Includes BER encoders/decoders for the
74 <ulink url="&url.ill;">ISO ILL</ulink>
81 <ulink url="&url.solr;">Solr</ulink> Web Service version 1.4.x
87 Supports the following transports: BER over TCP/IP
88 (<ulink url="&url.ber.over.tcpip;">RFC1729</ulink>),
89 BER over unix local socket, and
90 <ulink url="&url.http.1.1;">HTTP 1.1</ulink>.
95 Secure Socket Layer support using
96 <ulink url="&url.gnutls;">GnuTLS</ulink>.
97 If enabled, &yaz; uses HTTPS transport (for SOAP) or
98 "Secure BER" (for Z39.50).
104 <ulink url="&url.zoom;">ZOOM</ulink> C API implementing
105 Z39.50, SRU and Solr Web Service.
110 The &yaz; library offers a set of useful utilities
111 related to the protocols, such as MARC (ISO2709) parser,
112 CCL (ISO8777) parser,
113 <ulink url="&url.cql;">CQL</ulink>
114 parser, memory management routines, character set conversion.
119 Portable code. &yaz; compiles out-of-the box on most Unixes and
120 on Windows using Microsoft Visual C++.
125 Fast operation. The C based BER encoders/decoders as well
126 as the server component of &yaz; is very fast.
131 Liberal license that allows for commercial use of &yaz;.
137 <sect1 id="introduction.reading">
138 <title>Reading this Manual</title>
140 Most implementors only need to read a fraction of the
141 material in thie manual, so a quick walkthrough of the chapters
147 <xref linkend="installation"/> contains installation
148 instructions for &yaz;. You don't need reading this
149 if you expect to download &yaz; binaries.
150 However, the chapter contains information about how
151 to make <emphasis>your</emphasis> application link
157 <xref linkend="zoom"/> describes the ZOOM API of &yaz;.
158 This is definitely worth a read if you wish to develop a Z39.50/SRU
164 <xref linkend="server"/> describes the generic frontend server
165 and explains how to develop server Z39.50/SRU applications for &yaz;.
166 Obviously worth reading if you're to develop a server.
171 <xref linkend="yaz-client"/> describes how to use the &yaz; Z39.50
172 client. If you're developer and wish to test your server
173 or a server from another party, you might find this chapter
179 <xref linkend="asn"/> documents the most commonly used Z39.50
180 C data structures offered by the &yaz; API. Client
181 developers using ZOOM and non-Z39.50 implementors may skip this.
186 <xref linkend="soap"/> describes how SRU and SOAP is used
187 in &yaz;. Only if you're developing SRU applications
188 this section is a must.
193 <xref linkend="tools"/> contains sections for the various
194 tools offered by &yaz;. Scan through the material quickly
195 and see what's relevant to you! SRU implementors
196 might find the <link linkend="cql">CQL</link> section
202 <xref linkend="odr"/> goes through the details of the
203 ODR module which is the work horse that encodes and decodes
204 BER packages. Implementors using ZOOM only, do <emphasis>not</emphasis>
206 Most other Z39.50 implementors only need to read the first two
207 sections (<xref linkend="odr.introduction"/> and
208 <xref linkend="odr.use"/>).
213 <xref linkend="comstack"/> describes the network layer module
214 COMSTACK. Implementors using ZOOM or the generic frontend server
215 may skip this. Others, presumably, handling client/server
216 communication on their own should read this.
221 <sect1 id="introduction.api">
222 <title>The API</title>
224 The <ulink url="&url.yaz;">&yaz;</ulink>
225 toolkit offers several different levels of access to the
226 <ulink url="&url.z39.50;">ISO23950/Z39.50</ulink>,
227 <ulink url="&url.ill;">ILL</ulink> and
228 <ulink url="&url.sru;">SRU</ulink>
230 The level that you need to use depends on your requirements, and
231 the role (server or client) that you want to implement.
232 If you're developing a client application you should consider the
233 <link linkend="zoom">ZOOM</link> API.
234 It is, by far, the easiest way to develop clients in C.
235 Server implementers should consider the
236 <link linkend="server">generic frontend server</link>.
237 None of those high-level APIs support the whole protocol, but
238 they do include most facilities used in existing Z39.50 applications.
241 If you're using 'exotic' functionality (meaning anything not included in
242 the high-level APIs), developing non-standard extensions to Z39.50 or
243 you're going to develop an ILL application you'll have to learn the lower
247 The YAZ toolkit modules is shown in figure <xref linkend="yaz.layer"/>.
249 <figure id="yaz.layer">
250 <title>YAZ layers</title>
253 <imagedata fileref="apilayer.png" format="PNG"/>
256 <imagedata fileref="apilayer.eps" format="EPS"/>
261 There are four layers.
264 <para>A client or server application (or both).
265 This layer includes ZOOM and the generic frontend server.
270 The second layer provides a C represenation of the
271 protocol units (packages) for Z39.50 ASN.1, ILL ASN.1,
277 The third layer encodes and decodes protocol data units to
278 simple packages (buffer with certain length). The &odr; module
279 encodes and decodes BER whereas the HTTP modules encodes and
280 decodes HTTP ruquests/responses.
285 The lowest layer is &comstack; which exchanges the encoded packages
286 with a peer process over a network.
292 The &asn; module represents the ASN.1 definition of
293 the Z39.50 protocol. It establishes a set of type and
294 structure definitions, with one structure for each of the top-level
295 PDUs, and one structure or type for each of the contained ASN.1 types.
296 For primitive types, or other types that are defined by the ASN.1
297 standard itself (such as the EXTERNAL type), the C representation is
298 provided by the &odr; (Open Data Representation) subsystem.
301 &odr; is a basic mechanism for representing an
302 ASN.1 type in the C programming language, and for implementing BER
303 encoders and decoders for values of that type. The types defined in
304 the &asn; module generally have the prefix <literal>Z_</literal>, and
305 a suffix corresponding to the name of the type in the ASN.1
306 specification of the protocol (generally Z39.50-1995). In the case of
307 base types (those originating in the ASN.1 standard itself), the prefix
308 <literal>Odr_</literal> is sometimes seen. Either way, look for
309 the actual definition in either <filename>z-core.h</filename> (for the types
310 from the protocol), <filename>odr.h</filename> (for the primitive ASN.1
312 The &asn; library also provides functions (which are, in turn,
313 defined using &odr; primitives) for encoding and decoding data values.
314 Their general form is
316 <funcprototype><funcdef>int <function>z_<replaceable>xxx</replaceable></function></funcdef>
317 <paramdef>ODR <parameter>o</parameter></paramdef>
318 <paramdef>Z_<replaceable>xxx</replaceable> **<parameter>p</parameter></paramdef>
319 <paramdef>int <parameter>optional</parameter></paramdef>
320 <paramdef>const char *<parameter>name</parameter></paramdef>
323 (note the lower-case "z" in the function name)
327 If you are using the premade definitions of the &asn; module, and you
328 are not adding new protocol of your own, the only parts of &odr; that you
329 need to worry about are documented in
330 <xref linkend="odr.use"/>.
334 When you have created a BER-encoded buffer, you can use the &comstack;
335 subsystem to transmit (or receive) data over the network. The &comstack;
336 module provides simple functions for establishing a connection
337 (passively or actively, depending on the role of your application),
338 and for exchanging BER-encoded PDUs over that connection. When you
339 create a connection endpoint, you need to specify what transport to
340 use (TCP/IP, SSL or UNIX sockets).
341 For the remainder of the connection's lifetime, you don't have
342 to worry about the underlying transport protocol at all - the &comstack;
343 will ensure that the correct mechanism is used.
346 We call the combined interfaces to &odr;, &asn;, and &comstack; the service
347 level API. It's the API that most closely models the Z39.50
348 service/protocol definition, and it provides unlimited access to all
349 fields and facilities of the protocol definitions.
352 The reason that the &yaz; service-level API is a conglomerate of the
353 APIs from three different submodules is twofold. First, we wanted to allow
354 the user a choice of different options for each major task. For instance,
355 if you don't like the protocol API provided by &odr;/&asn;, you
356 can use SNACC or BERUtils instead, and still have the benefits of the
357 transparent transport approach of the &comstack; module. Secondly,
358 we realize that you may have to fit the toolkit into an existing
359 event-processing structure, in a way that is incompatible with
360 the &comstack; interface or some other part of &yaz;.
364 <chapter id="installation">
365 <title>Compilation and Installation</title>
366 <sect1 id="installation-introduction">
367 <title>Introduction</title>
369 The latest version of the software will generally be found at:
372 <ulink url="&url.yaz.download;"/>
375 We have tried our best to keep the software portable, and on many
376 platforms, you should be able to compile everything with little or
380 The software is regularly tested on
381 <ulink url="&url.debian;">Debian GNU/Linux</ulink>,
382 <ulink url="&url.centos;">CentOS</ulink>,
383 <ulink url="&url.ubuntu;">Ubuntu Linux</ulink>,
384 <ulink url="&url.freebsd;">FreeBSD (i386)</ulink>,
385 <ulink url="&url.macosx;">MAC OSX</ulink>,
386 <ulink url="&url.solaris;">Solaris</ulink>,
387 Windows 7, Windows XP.
390 Some versions have be known to work on HP/UX,
391 DEC Unix, <ulink url="&url.netbsd;">NetBSD</ulink>,
392 <ulink url="&url.openbsd;">OpenBSD</ulink>,
394 Data General DG/UX (with some CFLAGS tinkering),
395 SGI/IRIX, DDE Supermax, Apple Macintosh (using the Codewarrior programming
396 environment and the GUSI socket libraries),
400 If you move the software to other platforms, we'd be grateful if you'd
401 let us know about it. If you run into difficulties, we will try to help
402 if we can, and if you solve the problems, we would be happy to include
403 your fixes in the next release. So far, we have mostly avoided
404 <literal>#ifdefs</literal> for individual platforms, and we'd
405 like to keep it that way as far as it makes sense.
408 We maintain a mailing-list for the purpose of announcing new releases and
409 bug-fixes, as well as general discussion. Subscribe by
411 <ulink url="&url.yaz.mailinglist;">here</ulink>.
412 General questions and problems can be directed at
413 <ulink url="&url.yaz.mail;"/>, or the address given at the top of
417 <sect1 id="installation.unix"><title>UNIX</title>
420 <ulink url="&url.debian;">Debian GNU/Linux</ulink> (i386 and amd64),
421 <ulink url="&url.ubuntu;">Ubuntu</ulink> (i386 and amd64)
423 <ulink url="&url.centos;">CentOS</ulink> (amd64 only) packages for &yaz;.
424 You should be able to create packages for other CPUs by building
425 them from the source package.
428 YAZ is also part of several packages repositories. Some of them are
433 Solaris CSW: <ulink url="http://www.opencsw.org/packages/yaz/"/>
438 Solaris: <ulink url="http://unixpackages.com"/>
443 FreeBSD: <ulink url="http://www.freshports.org/net/yaz"/>
448 Debian: <ulink url="http://packages.debian.org/search?keywords=yaz"/>
453 Ubuntu: <ulink url="https://launchpad.net/ubuntu/+source/yaz"/>
459 <ulink url="http://ftp.netbsd.org/pub/pkgsrc/current/pkgsrc/net/yaz/README.html"/>
463 <sect2 id="installation.source.unix">
464 <title>Compiling from source on Unix</title>
466 Note that if your system doesn't have a native ANSI C compiler, you may
467 have to acquire one separately. We recommend
468 <ulink url="&url.gcc;">GCC</ulink>.
471 If you wish to use character set conversion facilities in &yaz; or if you
472 are compiling &yaz; for use with Zebra it is a good idea to ensure that
473 the iconv library is installed. Some Unixes today already have it
475 <ulink url="&url.libiconv;">GNU libiconv</ulink>.
478 YAZ 3.0.16 and later includes a wrapper for the
479 <ulink url="&url.icu;">ICU</ulink>
480 (International Components for Unicode).
481 In order to use this, the developer version of the ICU library
482 must be available. ICU support is recommended for applications
483 such as Pazpar2 and Zebra.
486 The <ulink url="&url.libxslt;">libxslt</ulink>,
487 <ulink url="&url.libxml2;">libxml2</ulink> librararies are required
488 if &yaz; is to support SRU/Solr.
489 These libraries are very portable and should compile out-of-the
490 box on virtually all Unix platforms. It is available in binary
491 forms for Linux and others.
495 <ulink url="&url.autoconf;">Autoconf</ulink>,
496 <ulink url="&url.automake;">Automake</ulink> and
497 <ulink url="&url.libtool;">Libtool</ulink>
498 are used to generate Makefiles and configure &yaz; for the system.
499 You do <emphasis>not</emphasis> these tools unless you're using the
500 Git version of &yaz;.
503 The CQL parser for &yaz; is built using
504 GNU <ulink url="&url.bison;">Bison</ulink>.
505 This tool is only needed if you're using the Git version of &yaz;.
508 &yaz; includes a tiny ASN.1 compiler. This compiler is
509 written in <ulink url="&url.tcl;">Tcl</ulink>.
510 But as for Bison you do not need it unless you're using Git
511 version of &yaz; or you're using the compiler to built own codecs
515 Generally it should be sufficient to run configure without options,
522 The configure script attempts to use use the C compiler specified by
523 the <literal>CC</literal> environment variable. If not set, GNU C will be
524 used if it is available. The <literal>CFLAGS</literal> environment
525 variable holds options to be passed to the C compiler. If you're using
526 Bourne-compatible shell you may pass something like this to use a
527 particular C compiler with optimization enabled:
530 CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
533 To customize &yaz;, the configure script also accepts a set of options.
534 The most important are:
538 <literal>--prefix</literal>=<replaceable>prefix</replaceable>
541 <para>Specifies installation prefix for &yaz;. This is
542 only needed if you run <literal>make install</literal> later to
543 perform a "system" installation. The prefix is
544 <literal>/usr/local</literal> if not specified.
550 <literal>--enable-tcpd</literal>
553 <para>The front end server will be built using Wietse's
554 <ulink url="&url.tcpwrapper;">TCP wrapper library</ulink>.
555 It allows you to allow/deny clients depending on IP number.
556 The TCP wrapper library is often used in GNU/Linux and
560 <refentrytitle>hosts_access</refentrytitle>
561 <manvolnum>5</manvolnum>
565 <refentrytitle>tcpd</refentrytitle>
566 <manvolnum>8</manvolnum>
573 <literal>--enable-threads</literal>
576 <para>&yaz; will be built using POSIX threads.
577 Specifically, <constant>_REENTRANT</constant> will be defined during
584 <literal>--disable-shared</literal>
587 <para>The make process will not create shared
588 libraries (also known as shared objects <filename>.so</filename>).
589 By default, shared libraries are created -
590 equivalent to <literal>--enable-shared</literal>.
596 <literal>--disable-shared</literal>
599 <para>The make process will not create
600 static libraries (<filename>.a</filename>).
601 By default, static libraries are created -
602 equivalent to <literal>--enable-static</literal>.
608 <literal>--with-iconv</literal>[=<replaceable>prefix</replaceable>]
611 <para>Compile &yaz; with iconv library in directory
612 <replaceable>prefix</replaceable>. By default configure will
613 search for iconv on the system. Use this option if it
614 doesn't find iconv. Alternatively,
615 <literal>--without-iconv</literal>, can be uset to force &yaz;
622 <literal>--with-xslt</literal>[=<replaceable>prefix</replaceable>]
625 <para>Compile &yaz; with
626 <ulink url="&url.libxslt;">libxslt</ulink> in directory
627 <replaceable>prefix</replaceable>.
628 Use this option if you want XSLT and XML support.
629 By default, configure will
630 search for libxslt on the system. Use this option if it
631 libxslt is not found automatically. Alternatively,
632 <literal>--without-xslt</literal>, can be used to force &yaz;
639 <literal>--with-xml2</literal>[=<replaceable>prefix</replaceable>]
642 <para>Compile &yaz; with
643 <ulink url="&url.libxml2;">libxml2</ulink> in directory
644 <replaceable>prefix</replaceable>.
645 Use this option if you want &yaz; to use XML and support SRU/Solr.
646 By default, configure will
647 search for libxml2 on the system. Use this option if it
648 libxml2 is not found automatically. Alternatively,
649 <literal>--without-xml2</literal>, can be used to force &yaz;
653 Note that option <literal>--with-xslt</literal>
654 also enables libxml2.
660 <literal>--with-gnutls</literal>[=<replaceable>prefix</replaceable>]
663 <para>&yaz; will be linked with the GNU TLS libraries and
664 an SSL COMSTACK will be provided. By default configure enables
665 SSL support for YAZ if the GNU TLS development libraries are found
672 <literal>--with-icu</literal>[=<replaceable>prefix</replaceable>]
675 <para>&yaz; will be linked the
676 <ulink url="&url.icu;">ICU</ulink> library in the prefix if given.
677 If prefix is not given, the libraries exposed by the script
678 <application>icu-config</application> will be used if found.
685 <literal>--with-libgcrypt</literal>[=<replaceable>prefix</replaceable>]
688 <para>&yaz; will be linked with
689 <ulink url="&url.libgcrypt;">Libgcrypt</ulink> in the prefix if given.
690 If prefix is not given, the libraries exposed by the script
691 <application>libgcrypt-config</application> will be used if found.
697 <literal>--with-memcached</literal>
700 <para>&yaz; will be linked with
701 <ulink url="&url.libmemcached;">libMemcached</ulink> to allow
702 for result-set caching for ZOOM.
703 The prefix can not be given. Note that YAZ will only search
704 for libMemcached if Libgcrypt is also enabled.
705 Note that 0.40 of libmemcached is required.
711 <literal>--with-redis</literal>
714 <para>&yaz; will be linked with the hiredis C library
715 to allow for result-set caching for ZOOM on a
716 <ulink url="&url.redis;">redis</ulink> server.
717 The prefix can not be given. Note that YAZ will only search
718 for hiredis if Libgcrypt is also enabled.
726 When configured, build the software by typing:
732 The following files are generated by the make process:
735 <term><filename>src/libyaz.la</filename></term>
737 Main &yaz; library. This is no ordinary library. It's
739 By default, &yaz; creates a static library in
740 <filename>lib/.libs/libyaz.a</filename>.
744 <term><filename>src/libyaz_server.la</filename></term>
746 Generic Frontend server. This is an add-on for libyaz.la.
747 Code in this library uses POSIX threads functions - if POSIX
748 threads are available on the platform.
752 <term><filename>src/libyaz_icu.la</filename></term>
754 Functions that wrap the ICU library.
758 <term><filename>ztest/yaz-ztest</filename></term>
759 <listitem><para>Test Z39.50 server.
763 <term><filename>client/yaz-client</filename></term>
764 <listitem><para>Z39.50 client for testing the protocol.
765 See chapter <link linkend="yaz-client">
766 YAZ client</link> for more information.
770 <term><filename>util/yaz-config</filename></term>
771 <listitem><para>A Bourne-shell script, generated by configure, that
772 specifies how external applications should compile - and link with
777 <term><filename>util/yaz-asncomp</filename></term>
778 <listitem><para>The ASN.1 compiler for &yaz;. Requires the
779 Tcl Shell, <application>tclsh</application>, in
780 <literal>PATH</literal> to operate.
784 <term><filename>util/yaz-iconv</filename></term>
785 <listitem><para>This program converts data in one character set to
786 another. This command exercises the YAZ character set
791 <term><filename>util/yaz-marcdump</filename></term>
792 <listitem><para>This program parses ISO2709 encoded MARC records
793 and prints them in line-format or XML.
797 <term><filename>util/yaz-icu</filename></term>
798 <listitem><para>This program exposes the ICU wrapper library if that
799 is enabled for YAZ. Only if ICU is available this program is
804 <term><filename>util/yaz-url</filename></term>
805 <listitem><para>This program is a simple HTTP page fetcher ala
810 <term><filename>zoom/zoomsh</filename></term>
812 A simple shell implemented on top of the
813 <link linkend="zoom">ZOOM</link> functions.
814 The shell is a command line application that allows you to enter
815 simple commands to perform ZOOM operations.
819 <term><filename>zoom/zoomtst1</filename>,
820 <filename>zoom/zoomtst2</filename>, ..</term>
822 Several small applications that demonstrates the ZOOM API.
828 If you wish to install &yaz; in system directories
829 <filename>/usr/local/bin</filename>,
830 <filename>/usr/local/lib</filename> .. etc, you can type:
836 You probably need to have root access in order to perform this.
837 You must specify the <literal>--prefix</literal> option for configure if
838 you wish to install &yaz; in other directories than the default
839 <filename>/usr/local/</filename>.
842 If you wish to perform an un-installation of &yaz;, use:
848 This will only work if you haven't reconfigured &yaz; (and therefore
849 changed installation prefix). Note that uninstall will not
850 remove directories created by make install, e.g.
851 <filename>/usr/local/include/yaz</filename>.
854 <sect2 id="installation-linking-yaz-unix">
855 <title>How to make apps using YAZ on UNIX</title>
857 This section describes how to compile - and link your own
858 applications using the &yaz; toolkit.
859 If you're used to Makefiles this shouldn't be hard. As for
860 other libraries you have used before, you have to set a proper include
861 path for your C/C++ compiler and specify the location of
862 &yaz; libraries. You can do it by hand, but generally we suggest
863 you use the <filename>yaz-config</filename> that is generated
864 by <filename>configure</filename>. This is especially
865 important if you're using the threaded version of &yaz; which
866 require you to pass more options to your linker/compiler.
869 The <filename>yaz-config</filename> script accepts command line
870 options that makes the <filename>yaz-config</filename> script print
871 options that you should use in your make process.
872 The most important ones are:
873 <literal>--cflags</literal>, <literal>--libs</literal>
874 which prints C compiler flags, and linker flags respectively.
877 A small and complete <literal>Makefile</literal> for a C
878 application consisting of one source file,
879 <filename>myprog.c</filename>, may look like this:
881 YAZCONFIG=/usr/local/bin/yaz-config
882 CFLAGS=`$(YAZCONFIG) --cflags`
883 LIBS=`$(YAZCONFIG) --libs`
885 $(CC) $(CFLAGS) -o myprog myprog.o $(LIBS)
889 The CFLAGS variable consists of a C compiler directive that will set
890 the include path to the <emphasis>parent</emphasis> directory
891 of <filename>yaz</filename>. That is, if &yaz; header files were
892 installed in <filename>/usr/local/include/yaz</filename>,
893 then include path is set to <filename>/usr/local/include</filename>.
894 Therefore, in your applications you should use
896 #include <yaz/proto.h>
898 and <emphasis>not</emphasis>
900 #include <proto.h>
904 For Libtool users, the <filename>yaz-config</filename> script provides
905 a different variant of option <literal>--libs</literal>, called
906 <literal>--lalibs</literal> that returns the name of the
907 Libtool archive(s) for &yaz; rather than the ordinary ones.
910 For applications using the threaded version of &yaz;,
911 specify <literal>threads</literal> after the
912 other options. When <literal>threads</literal> is given,
913 more flags and linker flags will be printed by
914 <filename>yaz-config</filename>. If our previous example was
915 using threads, you'd have to modify the lines that set
916 <literal>CFLAGS</literal> and <literal>LIBS</literal> as
919 CFLAGS=`$(YAZCONFIG) --cflags threads`
920 LIBS=`$(YAZCONFIG) --libs threads`
922 There is no need specify POSIX thread libraries in your Makefile.
923 The <literal>LIBS</literal> variable includes that as well.
927 <sect1 id="installation.win32">
928 <title>Windows</title>
929 <para>The easiest way to install YAZ on Windows is by downloading
931 <ulink url="&url.yaz.download.win32;">here</ulink>.
932 The installer comes with source too - in case you wish to
933 compile YAZ with different compiler options, etc.
936 <sect2 id="installation.win32.source">
937 <title>Compiling from Source on Windows</title>
939 &yaz; is shipped with "makefiles" for the NMAKE tool that comes
940 with <ulink url="&url.vstudio;">
941 Microsoft Visual Studio</ulink>. It has been tested with
942 Microsoft Visual Studio 2013.
945 Start a command prompt and switch the sub directory
946 <filename>WIN</filename> where the file <filename>makefile</filename>
947 is located. Customize the installation by editing the
948 <filename>makefile</filename> file (for example by using notepad).
949 The following summarizes the most important settings in that file:
952 <term><literal>DEBUG</literal></term>
954 If set to 1, the software is
955 compiled with debugging libraries (code generation is
956 multi-threaded debug DLL).
957 If set to 0, the software is compiled with release libraries
958 (code generation is multi-threaded DLL).
962 <term><literal>HAVE_TCL</literal>, <literal>TCL</literal></term>
964 If <literal>HAVE_TCL</literal> is set to 1, nmake will
965 use the ASN.1 compiler (<ulink url="&url.tcl;">Tcl</ulink> based).
966 You must set <literal>TCL</literal> to the full path of the Tcl
967 interpreter. A Windows version of Tcl is part of
968 <ulink url="&url.gitwindows;">Git for Windows</ulink>.
971 If you do not have Tcl installed, set
972 <literal>HAVE_TCL</literal> to 0.
976 <term><literal>HAVE_BISON</literal>,
977 <literal>BISON</literal></term>
979 If GNU Bison is present, you might set <literal>HAVE_BISON</literal>
980 to 1 and specify the Bison executable in <literal>BISON</literal>.
981 Bison is only required if you use the Git version of
982 YAZ or if you modify the grammar for CQL
983 (<filename>cql.y</filename>).
986 A Windows version of GNU Bison is part of
987 <ulink url="&url.gitwindows;">Git for Windows</ulink>.
991 <term><literal>HAVE_ICONV</literal>,
992 <literal>ICONV_DIR</literal></term>
994 If <literal>HAVE_ICONV</literal> is set to 1, YAZ is compiled
995 with iconv support. In this configuration, set
996 <literal>ICONV_DIR</literal> to the iconv source directory.
1000 <term><literal>HAVE_LIBXML2</literal>,
1001 <literal>LIBXML2_DIR</literal></term>
1004 If <literal>HAVE_LIBXML2</literal> is set to 1, YAZ is compiled
1005 with SRU support. In this configuration, set
1006 <literal>LIBXML2_DIR</literal> to the
1007 <ulink url="&url.libxml2;">libxml2</ulink> source directory.
1010 You can get pre-compiled Libxml2+Libxslt DLLs and headers from
1011 <ulink url="&url.libxml2.download.windows;">here</ulink>.
1012 Should you with to compile those libraries yourself, refer to
1013 to <xref linkend="installation.windows.libxml2"/>
1018 <term><literal>HAVE_LIBXSLT</literal>,
1019 <literal>LIBXSLT_DIR</literal></term>
1022 If <literal>HAVE_LIBXSLT</literal> is set to 1, YAZ is compiled
1023 with XSLT support. In this configuration, set
1024 <literal>LIBXSLT_DIR</literal> to the
1025 <ulink url="&url.libxslt;">libxslt</ulink> source directory.
1029 libxslt depends libxml2.
1035 <term><literal>HAVE_ICU</literal>,
1036 <literal>ICU_DIR</literal></term>
1039 If <literal>HAVE_ICU</literal> is set to 1, YAZ is compiled
1040 with <ulink url="&url.icu;">ICU</ulink> support.
1041 In this configuration, set
1042 <literal>ICU_DIR</literal> to the
1043 <ulink url="&url.icu;">ICU</ulink> source directory.
1050 When satisfied with the settings in the makefile, type
1057 If the <filename>nmake</filename> command is not found on your system
1058 you probably haven't defined the environment variables required to
1059 use that tool. To fix that, find and run the batch file
1060 <filename>vcvars32.bat</filename>. You need to run it from within
1061 the command prompt or set the environment variables "globally";
1062 otherwise it doesn't work.
1066 If you wish to recompile &yaz; - for example if you modify
1067 settings in the <filename>makefile</filename> you can delete
1068 object files, etc by running.
1074 The following files are generated upon successful compilation:
1077 <term><filename>bin/yaz&soversion;.dll</filename> /
1078 <filename>bin/yaz&soversion;d.dll</filename></term>
1080 &yaz; Release/Debug DLL.
1084 <term><filename>lib/yaz&soversion;.lib</filename> /
1085 <filename>lib/yaz&soversion;d.lib</filename></term>
1087 Import library for <filename>yaz&soversion;.dll</filename> /
1088 <filename>yaz&soversion;d.dll</filename>.
1092 <term><filename>bin/yaz_cond&soversion;.dll</filename> /
1093 <filename>bin/yaz_cond&soversion;d.dll</filename></term>
1095 Release/Debug DLL for condition variable utilities (condvar.c).
1099 <term><filename>lib/yaz_cond&soversion;.lib</filename> /
1100 <filename>lib/yaz_cond&soversion;d.lib</filename></term>
1102 Import library for <filename>yaz_cond&soversion;.dll</filename> /
1103 <filename>yaz_cond&soversion;d.dll</filename>.
1107 <term><filename>bin/yaz_icu&soversion;.dll</filename> /
1108 <filename>bin/yaz_icu&soversion;d.dll</filename></term>
1110 Release/Debug DLL for the ICU wrapper utility.
1111 Only build if HAVE_ICU is 1.
1115 <term><filename>lib/yaz_icu&soversion;.lib</filename> /
1116 <filename>lib/yaz_icu&soversion;d.lib</filename></term>
1118 Import library for <filename>yaz_icu&soversion;.dll</filename> /
1119 <filename>yaz_icu&soversion;d.dll</filename>.
1123 <term><filename>bin/yaz-ztest.exe</filename></term>
1125 Z39.50 multi-threaded test/example server. It's a WIN32
1126 console application.
1130 <term><filename>bin/yaz-client.exe</filename></term>
1132 &yaz; Z39.50 client application. It's a WIN32 console application.
1133 See chapter <link linkend="yaz-client">YAZ client</link> for more
1138 <term><filename>bin/yaz-icu.exe</filename></term>
1139 <listitem><para>This program exposes the ICU wrapper library if that
1140 is enabled for YAZ. Only if ICU is available this program is
1145 <term><filename>bin/zoomsh.exe</filename></term>
1147 Simple console application implemented on top of the
1148 <link linkend="zoom">ZOOM</link> functions.
1149 The application is a command line shell that allows you to enter
1150 simple commands to perform ZOOM operations.
1154 <term><filename>bin/zoomtst1.exe</filename>,
1155 <filename>bin/zoomtst2.exe</filename>, ..</term>
1157 Several small applications that demonstrates the ZOOM API.
1164 <sect2 id="installation-linking-yaz-win32">
1165 <title>How to make apps using YAZ on Windows</title>
1167 This section will go though the process of linking your Windows
1168 applications with &yaz;.
1171 Some people are confused by the fact that we use the nmake
1172 tool to build &yaz;. They think they have to do that too - in order
1173 to make their Windows applications work with &yaz;. The good news is that
1174 you don't have to. You can use the integrated environment of
1175 Visual Studio if desired for your own application.
1178 When setting up a project or Makefile you have to set the following:
1181 <term>include path</term>
1183 Set it to the <filename>include</filename> directory of &yaz;.
1187 <term>import library <filename>yaz&soversion;.lib</filename></term>
1189 You must link with this library. It's located in the
1190 sub directory <filename>lib</filename> of &yaz;.
1191 If you want to link with the debug version of &yaz;, you must
1192 link against <filename>yaz&soversion;d.lib</filename> instead.
1196 <term>dynamic link library
1197 <filename>yaz&soversion;.dll</filename>
1200 This DLL must be in your execution path when you invoke
1201 your application. Specifically, you should distribute this
1202 DLL with your application.
1209 <sect2 id="installation.windows.libxml2">
1210 <title>Compiling Libxml2 and Libxslt on windows</title>
1212 Download libxml2 and Libxslt source and unpack it.
1213 In the example below we install Libxml2 2.9.2 and Libxslt 1.1.28
1214 for 32-bit, so we use the destination directories
1215 libxml2.2.9.2.win32 and libxslt-1.1.28.win32 to reflect both
1216 version and architecture.
1219 cscript configure.js prefix=c:\libxml2-2.9.2.win32 iconv=no
1225 For Libxslt it is similar. We must ensure that compilation of
1226 Libxslt links against the already installed libxml2.
1229 cscript configure.js prefix=c:\libxslt-1.1.28.win32 iconv=no \
1230 lib=c:\libxmlt-2.9.2.win32\lib \
1231 include=c:\libxmlt-2.9.2.win32\include\libxml2
1241 ### Still to document:
1242 ZOOM_connection_errcode(c)
1243 ZOOM_connection_errmsg(c)
1244 ZOOM_connection_addinfo(c)
1245 ZOOM_connection_addinfo(c)
1246 ZOOM_connection_diagset(c);
1247 ZOOM_connection_save_apdu_wrbuf
1248 ZOOM_diag_str(error)
1249 ZOOM_resultset_record_immediate(s, pos)
1250 ZOOM_resultset_cache_reset(r)
1251 ZOOM_options_set_callback(opt, function, handle)
1252 ZOOM_options_create_with_parent2(parent1, parent2)
1253 ZOOM_options_getl(opt, name, len)
1254 ZOOM_options_setl(opt, name, value, len)
1255 ZOOM_options_get_bool(opt, name, defa)
1256 ZOOM_options_get_int(opt, name, defa)
1257 ZOOM_options_set_int(opt, name, value)
1262 &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is
1263 an initiative started by Mike Taylor (Mike is from the UK, which
1264 explains the peculiar name of the model). The goal of &zoom; is to
1265 provide a common Z39.50 client API not bound to a particular
1266 programming language or toolkit.
1269 From YAZ version 2.1.12, <ulink url="&url.sru;">SRU</ulink> is supported.
1270 You can make SRU ZOOM connections by specifying scheme
1271 <literal>http://</literal> for the hostname for a connection.
1272 The dialect of SRU used is specified by the value of the
1273 connection's <literal>sru</literal> option, which may be SRU over
1274 HTTP GET (<literal>get</literal>),
1275 SRU over HTTP POST (<literal>post</literal>), (SRU over
1276 SOAP) (<literal>soap</literal>) or <literal>solr</literal>
1277 (<ulink url="&url.solr;">Solr</ulink> Web Service).
1278 Using the facility for embedding options in target strings, a
1279 connection can be forced to use SRU rather the SRW (the default) by
1280 prefixing the target string with <literal>sru=get,</literal>, like this:
1281 <literal>sru=get,http://sru.miketaylor.org.uk:80/sru.pl</literal>
1284 <ulink url="&url.solr;">Solr</ulink> protocol support was added to
1285 YAZ in version 4.1.0, as a dialect of a SRU protocol, since both are
1286 HTTP based protocols.
1289 The lack of a simple Z39.50 client API for &yaz; has become more
1290 and more apparent over time. So when the first &zoom; specification
1292 an implementation for &yaz; was quickly developed. For the first time, it is
1293 now as easy (or easier!) to develop clients than servers with &yaz;. This
1294 chapter describes the &zoom; C binding. Before going further, please
1295 reconsider whether C is the right programming language for the job.
1296 There are other language bindings available for &yaz;, and still
1298 are in active development. See the
1299 <ulink url="&url.zoom;">ZOOM web-site</ulink> for
1303 In order to fully understand this chapter you should read and
1304 try the example programs <literal>zoomtst1.c</literal>,
1305 <literal>zoomtst2.c</literal>, .. in the <literal>zoom</literal>
1309 The C language misses features found in object oriented languages
1310 such as C++, Java, etc. For example, you'll have to manually,
1311 destroy all objects you create, even though you may think of them as
1312 temporary. Most objects has a <literal>_create</literal> - and a
1313 <literal>_destroy</literal> variant.
1314 All objects are in fact pointers to internal stuff, but you don't see
1315 that because of typedefs. All destroy methods should gracefully ignore a
1316 <literal>NULL</literal> pointer.
1319 In each of the sections below you'll find a sub section called
1320 protocol behavior, that describes how the API maps to the Z39.50
1323 <sect1 id="zoom-connections">
1324 <title>Connections</title>
1325 <para>The Connection object is a session with a target.
1328 #include <yaz/zoom.h>
1330 ZOOM_connection ZOOM_connection_new(const char *host, int portnum);
1332 ZOOM_connection ZOOM_connection_create(ZOOM_options options);
1334 void ZOOM_connection_connect(ZOOM_connection c, const char *host,
1336 void ZOOM_connection_destroy(ZOOM_connection c);
1339 Connection objects are created with either function
1340 <function>ZOOM_connection_new</function> or
1341 <function>ZOOM_connection_create</function>.
1342 The former creates and automatically attempts to establish a network
1343 connection with the target. The latter doesn't establish
1344 a connection immediately, thus allowing you to specify options
1345 before establishing network connection using the function
1346 <function>ZOOM_connection_connect</function>.
1347 If the port number, <literal>portnum</literal>, is zero, the
1348 <literal>host</literal> is consulted for a port specification.
1349 If no port is given, 210 is used. A colon denotes the beginning of
1350 a port number in the host string. If the host string includes a
1351 slash, the following part specifies a database for the connection.
1354 You can prefix the host with a scheme followed by colon. The
1355 default scheme is <literal>tcp</literal> (Z39.50 protocol).
1356 The scheme <literal>http</literal> selects SRU/get over HTTP by default,
1357 but can overridded to use SRU/post, SRW and the Solr protocol.
1360 You can prefix the scheme-qualified host-string with one or more
1362 <literal><parameter>key</parameter>=<parameter>value</parameter></literal>
1363 sequences, each of which represents an option to be set into the
1364 connection structure <emphasis>before</emphasis> the
1365 protocol-level connection is forged and the initialization
1366 handshake takes place. This facility can be used to provide
1367 authentication credentials, as in host-strings such as:
1368 <literal>user=admin,password=halfAm4n,tcp:localhost:8017/db</literal>
1371 Connection objects should be destroyed using the function
1372 <function>ZOOM_connection_destroy</function>.
1375 void ZOOM_connection_option_set(ZOOM_connection c,
1376 const char *key, const char *val);
1378 void ZOOM_connection_option_setl(ZOOM_connection c,
1380 const char *val, int len);
1382 const char *ZOOM_connection_option_get(ZOOM_connection c,
1384 const char *ZOOM_connection_option_getl(ZOOM_connection c,
1389 The functions <function>ZOOM_connection_option_set</function> and
1390 <function>ZOOM_connection_option_setl</function> allows you to
1391 set an option given by <parameter>key</parameter> to the value
1392 <parameter>value</parameter> for the connection.
1393 For <function>ZOOM_connection_option_set</function>, the
1394 value is assumed to be a 0-terminated string. Function
1395 <function>ZOOM_connection_option_setl</function> specifies a
1396 value of a certain size (len).
1399 Functions <function>ZOOM_connection_option_get</function> and
1400 <function>ZOOM_connection_option_getl</function> returns
1401 the value for an option given by <parameter>key</parameter>.
1403 <table id="zoom-connection-options" frame="top">
1404 <title>ZOOM Connection Options</title>
1406 <colspec colwidth="4*" colname="name"></colspec>
1407 <colspec colwidth="7*" colname="description"></colspec>
1408 <colspec colwidth="3*" colname="default"></colspec>
1411 <entry>Option</entry>
1412 <entry>Description</entry>
1413 <entry>Default</entry>
1418 implementationName</entry><entry>Name of Your client
1419 </entry><entry>none</entry></row>
1421 user</entry><entry>Authentication user name
1422 </entry><entry>none</entry></row>
1424 group</entry><entry>Authentication group name
1425 </entry><entry>none</entry></row>
1427 password</entry><entry>Authentication password.
1428 </entry><entry>none</entry></row>
1430 authenticationMode</entry><entry>How authentication is encoded.
1431 </entry><entry>basic</entry></row>
1433 host</entry><entry>Target host. This setting is "read-only".
1434 It's automatically set internally when connecting to a target.
1435 </entry><entry>none</entry></row>
1437 proxy</entry><entry>Proxy host. If set, the logical host
1438 is encoded in the otherInfo area of the Z39.50 Init PDU
1439 with OID 1.2.840.10003.10.1000.81.1.
1440 </entry><entry>none</entry></row>
1442 clientIP</entry><entry>Client IP. If set, is
1443 encoded in the otherInfo area of a Z39.50 PDU with OID
1444 1.2.840.10003.10.1000.81.3. Holds the original IP addreses
1445 of a client. Is used of ZOOM is used in a gateway of some sort.
1446 </entry><entry>none</entry></row>
1448 async</entry><entry>If true (1) the connection operates in
1449 asynchronous operation which means that all calls are non-blocking
1451 <link linkend="zoom.events"><function>ZOOM_event</function></link>.
1452 </entry><entry>0</entry></row>
1454 maximumRecordSize</entry><entry> Maximum size of single record.
1455 </entry><entry>1 MB</entry></row>
1457 preferredMessageSize</entry><entry> Maximum size of multiple records.
1458 </entry><entry>1 MB</entry></row>
1460 lang</entry><entry> Language for negotiation.
1461 </entry><entry>none</entry></row>
1463 charset</entry><entry> Character set for negotiation.
1464 </entry><entry>none</entry></row>
1466 serverImplementationId</entry><entry>
1467 Implementation ID of server. (The old targetImplementationId
1468 option is also supported for the benefit of old applications.)
1469 </entry><entry>none</entry></row>
1471 targetImplementationName</entry><entry>
1472 Implementation Name of server. (The old
1473 targetImplementationName option is also supported for the
1474 benefit of old applications.)
1475 </entry><entry>none</entry></row>
1477 serverImplementationVersion</entry><entry>
1478 Implementation Version of server. (the old
1479 targetImplementationVersion option is also supported for the
1480 benefit of old applications.)
1481 </entry><entry>none</entry></row>
1483 databaseName</entry><entry>One or more database names
1484 separated by character plus (<literal>+</literal>), which to
1485 be used by subsequent search requests on this Connection.
1486 </entry><entry>Default</entry></row>
1488 piggyback</entry><entry>True (1) if piggyback should be
1489 used in searches; false (0) if not.
1490 </entry><entry>1</entry></row>
1492 smallSetUpperBound</entry><entry>If hits is less than or equal to this
1493 value, then target will return all records using small element set name
1494 </entry><entry>0</entry></row>
1496 largeSetLowerBound</entry><entry>If hits is greater than this
1497 value, the target will return no records.
1498 </entry><entry>1</entry></row>
1500 mediumSetPresentNumber</entry><entry>This value represents
1501 the number of records to be returned as part of a search when when
1502 hits is less than or equal to large set lower bound and if hits
1503 is greater than small set upper bound.
1504 </entry><entry>0</entry></row>
1506 smallSetElementSetName</entry><entry>
1507 The element set name to be used for small result sets.
1508 </entry><entry>none</entry></row>
1510 mediumSetElementSetName</entry><entry>
1511 The element set name to be for medium-sized result sets.
1512 </entry><entry>none</entry></row>
1514 init_opt_search, init_opt_present, init_opt_delSet, etc.</entry><entry>
1515 After a successful Init, these options may be interrogated to
1516 discover whether the server claims to support the specified
1518 </entry><entry>none</entry></row>
1520 <entry>sru</entry><entry>
1521 SRU/Solr transport type. Must be either <literal>soap</literal>,
1522 <literal>get</literal>, <literal>post</literal>, or
1523 <literal>solr</literal>.
1524 </entry><entry>soap</entry></row>
1526 sru_version</entry><entry>
1527 SRU/SRW version. Should be <literal>1.1</literal>, or
1528 <literal>1.2</literal>. This is , prior to connect, the version
1529 to offer (highest version). And following connect (in fact
1530 first operation), holds the negotiated version with the server
1531 (same or lower version).
1532 </entry><entry>1.2</entry></row>
1533 <row id="zoom.facets.option"><entry>
1534 facets</entry><entry>
1535 Requested or recommend facets may be given before a search is sent.
1536 The value of this setting is described in <xref linkend="facets"/>
1537 For inspection of the facets returned, refer to the functions
1538 described in <xref linkend="zoom.facets"/>.
1539 </entry><entry>none</entry></row>
1541 apdulog</entry><entry>
1542 If set to a true value such as "1", a log of low-level
1543 protocol packets is emitted on standard error stream. This
1544 can be very useful for debugging.
1545 </entry><entry>0</entry></row>
1547 saveAPDU</entry><entry>
1548 If set to a true value such as "1", a log of low-level
1549 protocol packets is saved. The log can be retrieved by reading
1550 option APDU. Setting saveAPDU always has the side effect of
1551 resetting the currently saved log. This setting is
1552 <emphasis>write-only</emphasis>. If read, NULL will be returned.
1553 It is only recognized in
1554 <function>ZOOM_connection_option_set</function>.
1555 </entry><entry>0</entry></row>
1558 Returns the log of protocol packets. Will be empty if logging
1559 is not enabled (see saveAPDU above). This setting is
1560 <emphasis>read-only</emphasis>. It is only recognized if used
1561 in call to <function>ZOOM_connection_option_get</function> or
1562 <function>ZOOM_connection_option_getl</function>.
1563 </entry><entry></entry></row>
1565 memcached</entry><entry>
1566 If given and non-empty,
1567 <ulink url="&url.libmemcached;">libMemcached</ulink>
1568 will be configured for the connection.
1569 This option is inspected by ZOOM when a connection is established.
1570 If the <literal>memcached</literal> option is given
1571 and YAZ is compiled without libMemcached support, an internal
1572 diagnostic (10018) will be thrown.
1573 libMemcached support is available for YAZ 5.0.13 or later. If this
1574 option is supplied for an earlier version of YAZ, it is
1575 <emphasis>ignored</emphasis>.
1576 The value of this option is a list options - each is of the
1577 form <literal>--name=value</literal>.
1578 Option <literal>--server=</literal>host[:port] specifies a memcached
1579 server. It may be repeated for multiple memcached servers.
1580 Option <literal>--expire=</literal>seconds sets expiry time in seconds
1581 for how long result sets are to be cached.
1582 </entry><entry>none</entry></row>
1584 redis</entry><entry>
1585 If given and non-empty,
1586 a <ulink url="&url.redis;">redis</ulink> context will be created
1588 This option is inspected by ZOOM when a connection is established.
1589 If the <literal>redis</literal> option is given
1590 and YAZ is compiled without redis support, an internal
1591 diagnostic (10018) will be thrown.
1592 redis support is available for YAZ 5.2.0 or later. If this
1593 option is supplied for an earlier version of YAZ, it is
1594 <emphasis>ignored</emphasis>.
1595 The value of this option is a set options, similar to that
1596 of the memcached setting. At this stage only --server=host[:port]
1597 and --expire=seconds is supported.
1598 </entry><entry>none</entry></row>
1603 If either option <literal>lang</literal> or <literal>charset</literal>
1605 <ulink url="&url.z39.50.charneg;">
1606 Character Set and Language Negotiation</ulink> is in effect.
1609 int ZOOM_connection_error(ZOOM_connection c, const char **cp,
1610 const char **addinfo);
1611 int ZOOM_connection_error_x(ZOOM_connection c, const char **cp,
1612 const char **addinfo, const char **dset);
1615 Function <function>ZOOM_connection_error</function> checks for
1616 errors for the last operation(s) performed. The function returns
1617 zero if no errors occurred; non-zero otherwise indicating the error.
1618 Pointers <parameter>cp</parameter> and <parameter>addinfo</parameter>
1619 holds messages for the error and additional-info if passed as
1620 non-<literal>NULL</literal>. Function
1621 <function>ZOOM_connection_error_x</function> is an extended version
1622 of <function>ZOOM_connection_error</function> that is capable of
1623 returning name of diagnostic set in <parameter>dset</parameter>.
1625 <sect2 id="zoom-connection-z39.50">
1626 <title>Z39.50 Protocol behavior</title>
1628 The calls <function>ZOOM_connection_new</function> and
1629 <function>ZOOM_connection_connect</function> establishes a TCP/IP
1630 connection and sends an Initialize Request to the target if
1631 possible. In addition, the calls waits for an Initialize Response
1632 from the target and the result is inspected (OK or rejected).
1635 If <literal>proxy</literal> is set then the client will establish
1636 a TCP/IP connection with the peer as specified by the
1637 <literal>proxy</literal> host and the hostname as part of the
1638 connect calls will be set as part of the Initialize Request.
1639 The proxy server will then "forward" the PDU's transparently
1640 to the target behind the proxy.
1643 For the authentication parameters, if option <literal>user</literal>
1644 is set and both options <literal>group</literal> and
1645 <literal>pass</literal> are unset, then Open style
1646 authentication is used (Version 2/3) in which case the username
1647 is usually followed by a slash, then by a password.
1648 If either <literal>group</literal>
1649 or <literal>pass</literal> is set then idPass authentication
1650 (Version 3 only) is used. If none of the options are set, no
1651 authentication parameters are set as part of the Initialize Request
1655 When option <literal>async</literal> is 1, it really means that
1656 all network operations are postponed (and queued) until the
1657 function <literal>ZOOM_event</literal> is invoked. When doing so
1658 it doesn't make sense to check for errors after
1659 <literal>ZOOM_connection_new</literal> is called since that
1660 operation "connecting - and init" is still incomplete and the
1661 API cannot tell the outcome (yet).
1664 <sect2 id="zoom.sru.init.behavior">
1665 <title>SRU/Solr Protocol behavior</title>
1667 The HTTP based protocols (SRU, SRW, Solr) doesn't feature an
1668 Inititialize Request, so the connection phase merely establishes a
1669 TCP/IP connection with the HTTP server.
1671 <para>Most of the ZOOM connection options do not
1672 affect SRU/Solr and they are ignored. However, future versions
1673 of &yaz; might honor <literal>implementationName</literal> and
1674 put that as part of User-Agent header for HTTP requests.
1677 The <literal>charset</literal> is used in the Content-Type header
1681 Setting <literal>authentcationMode</literal> specifies how
1682 authentication parameters are encoded for HTTP. The default is
1683 "<literal>basic</literal>" where <literal>user</literal> and
1684 <literal>password</literal> are encoded by using HTTP basic
1688 If <literal>authentcationMode</literal> is "<literal>url</literal>", then
1689 user and password are encoded in the URL by parameters
1690 <literal>x-username</literal> and <literal>x-password</literal> as
1691 given by the SRU standard.
1695 <sect1 id="zoom.query">
1696 <title>Queries</title>
1698 Query objects represents queries.
1701 ZOOM_query ZOOM_query_create(void);
1703 void ZOOM_query_destroy(ZOOM_query q);
1705 int ZOOM_query_prefix(ZOOM_query q, const char *str);
1707 int ZOOM_query_cql(ZOOM_query s, const char *str);
1709 int ZOOM_query_sortby(ZOOM_query q, const char *criteria);
1711 int ZOOM_query_sortby2(ZOOM_query q, const char *strategy,
1712 const char *criteria);
1715 Create query objects using <function>ZOOM_query_create</function>
1716 and destroy them by calling <function>ZOOM_query_destroy</function>.
1717 RPN-queries can be specified in <link linkend="PQF">PQF</link>
1718 notation by using the
1719 function <function>ZOOM_query_prefix</function>.
1720 The <function>ZOOM_query_cql</function> specifies a CQL
1721 query to be sent to the server/target.
1722 More query types will be added in future versions of &yaz;, such as
1723 <link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
1724 etc. In addition to a search, a sort criteria may be set. Function
1725 <function>ZOOM_query_sortby</function> enables Z39.50 sorting and
1726 it takes sort criteria using the same string notation as
1727 yaz-client's <link linkend="sortspec">sort command</link>.
1729 <para id="zoom.query.sortby2">
1730 <function>ZOOM_query_sortby2</function> is similar to
1731 <function>ZOOM_query_sortby</function> but allows a strategy for
1732 sorting. The reason for the strategy parameter is that some
1733 protocols offers multiple ways of performing sorting.
1734 For example, Z39.50 has the standard sort, which is performed after
1735 search on an existing result set.
1736 It's also possible to use CQL in Z39.50 as the query type and use
1737 CQL's SORTBY keyword. Finally, Index Data's
1738 Zebra server also allows sorting to be specified as part of RPN (Type 7).
1740 <table id="zoom-sort-strategy" frame="top">
1741 <title>ZOOM sort strategy</title>
1743 <colspec colwidth="2*" colname="name"/>
1744 <colspec colwidth="5*" colname="description"/>
1748 <entry>Description</entry>
1753 <entry>z39.50</entry><entry>Z39.50 resultset sort</entry>
1756 <entry>type7</entry><entry>Sorting embedded in RPN(Type-7)</entry>
1759 <entry>cql</entry><entry>CQL SORTBY</entry>
1762 <entry>sru11</entry><entry>SRU sortKeys parameter</entry>
1765 <entry>solr</entry><entry>Solr sort</entry>
1768 <entry>embed</entry><entry>type7 for Z39.50, cql for SRU,
1769 solr for Solr protocol</entry>
1775 <sect1 id="zoom.resultsets"><title>Result sets</title>
1777 The result set object is a container for records returned from
1781 ZOOM_resultset ZOOM_connection_search(ZOOM_connection, ZOOM_query q);
1783 ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c,
1785 void ZOOM_resultset_destroy(ZOOM_resultset r);
1788 Function <function>ZOOM_connection_search</function> creates
1789 a result set given a connection and query.
1790 Destroy a result set by calling
1791 <function>ZOOM_resultset_destroy</function>.
1792 Simple clients may using PQF only may use function
1793 <function>ZOOM_connection_search_pqf</function> in which case
1794 creating query objects is not necessary.
1797 void ZOOM_resultset_option_set(ZOOM_resultset r,
1798 const char *key, const char *val);
1800 const char *ZOOM_resultset_option_get(ZOOM_resultset r, const char *key);
1802 size_t ZOOM_resultset_size(ZOOM_resultset r);
1805 Functions <function>ZOOM_resultset_options_set</function> and
1806 <function>ZOOM_resultset_get</function> sets and gets an option
1807 for a result set similar to <function>ZOOM_connection_option_get</function>
1808 and <function>ZOOM_connection_option_set</function>.
1811 The number of hits also called result-count is returned by
1812 function <function>ZOOM_resultset_size</function>.
1814 <table id="zoom.resultset.options"
1815 frame="top"><title>ZOOM Result set Options</title>
1817 <colspec colwidth="4*" colname="name"></colspec>
1818 <colspec colwidth="7*" colname="description"></colspec>
1819 <colspec colwidth="2*" colname="default"></colspec>
1822 <entry>Option</entry>
1823 <entry>Description</entry>
1824 <entry>Default</entry>
1829 start</entry><entry>Offset of first record to be
1830 retrieved from target. First record has offset 0 unlike the
1831 protocol specifications where first record has position 1.
1832 This option affects ZOOM_resultset_search and
1833 ZOOM_resultset_search_pqf and must be set before any of
1834 these functions are invoked. If a range of
1835 records must be fetched manually after search,
1836 function ZOOM_resultset_records should be used.
1837 </entry><entry>0</entry></row>
1839 count</entry><entry>Number of records to be retrieved.
1840 This option affects ZOOM_resultset_search and
1841 ZOOM_resultset_search_pqf and must be set before any of
1842 these functions are invoked.
1843 </entry><entry>0</entry></row>
1845 presentChunk</entry><entry>The number of records to be
1846 requested from the server in each chunk (present request). The
1847 value 0 means to request all the records in a single chunk.
1848 (The old <literal>step</literal>
1849 option is also supported for the benefit of old applications.)
1850 </entry><entry>0</entry></row>
1852 elementSetName</entry><entry>Element-Set name of records.
1853 Most targets should honor element set name <literal>B</literal>
1854 and <literal>F</literal> for brief and full respectively.
1855 </entry><entry>none</entry></row>
1857 preferredRecordSyntax</entry><entry>Preferred Syntax, such as
1858 <literal>USMARC</literal>, <literal>SUTRS</literal>, etc.
1859 </entry><entry>none</entry></row>
1861 schema</entry><entry>Schema for retrieval, such as
1862 <literal>Gils-schema</literal>, <literal>Geo-schema</literal>, etc.
1863 </entry><entry>none</entry></row>
1865 setname</entry><entry>Name of Result Set (Result Set ID).
1866 If this option isn't set, the ZOOM module will automatically
1867 allocate a result set name.
1868 </entry><entry>default</entry></row>
1870 rpnCharset</entry><entry>Character set for RPN terms.
1871 If this is set, ZOOM C will assume that the ZOOM application is
1872 running UTF-8. Terms in RPN queries are then converted to the
1873 rpnCharset. If this is unset, ZOOM C will not assume any encoding
1874 of RPN terms and no conversion is performed.
1875 </entry><entry>none</entry></row>
1880 For servers that support Search Info report, the following
1881 options may be read using <function>ZOOM_resultset_get</function>.
1882 This detailed information is read after a successful search has
1886 This information is a list of of items, where each item is
1887 information about a term or subquery. All items in the list
1889 <literal>SearchResult.</literal><replaceable>no</replaceable>
1890 where no presents the item number (0=first, 1=second).
1891 Read <literal>searchresult.size</literal> to determine the
1894 <table id="zoom.search.info.report.options"
1895 frame="top"><title>Search Info Report Options</title>
1897 <colspec colwidth="4*" colname="name"></colspec>
1898 <colspec colwidth="7*" colname="description"></colspec>
1901 <entry>Option</entry>
1902 <entry>Description</entry>
1907 <entry>searchresult.size</entry>
1909 number of search result entries. This option is-nonexistant
1910 if no entries are returned by the server.
1914 <entry>searchresult.<replaceable>no</replaceable>.id</entry>
1915 <entry>sub query ID</entry>
1918 <entry>searchresult.<replaceable>no</replaceable>.count</entry>
1919 <entry>result count for item (number of hits)</entry>
1922 <entry>searchresult.<replaceable>no</replaceable>.subquery.term</entry>
1923 <entry>subquery term</entry>
1927 searchresult.<replaceable>no</replaceable>.interpretation.term
1929 <entry>interpretation term</entry>
1933 searchresult.<replaceable>no</replaceable>.recommendation.term
1935 <entry>recommendation term</entry>
1940 <sect2 id="zoom.z3950.resultset.sort">
1941 <title>Z39.50 Result-set Sort</title>
1943 void ZOOM_resultset_sort(ZOOM_resultset r,
1944 const char *sort_type, const char *sort_spec);
1946 int ZOOM_resultset_sort1(ZOOM_resultset r,
1947 const char *sort_type, const char *sort_spec);
1950 <function>ZOOM_resultset_sort</function> and
1951 <function>ZOOM_resultset_sort1</function> both sort an existing
1952 result-set. The sort_type parameter is not use. Set it to "yaz".
1953 The sort_spec is same notation as ZOOM_query_sortby and identical
1954 to that offered by yaz-client's
1955 <link linkend="sortspec">sort command</link>.
1958 These functions only work for Z39.50. Use the more generic utility
1959 <link linkend="zoom.query.sortby2">
1960 <function>ZOOM_query_sortby2</function></link>
1961 for other protocols (and even Z39.50).
1964 <sect2 id="zoom.z3950.resultset.behavior">
1965 <title>Z39.50 Protocol behavior</title>
1967 The creation of a result set involves at least a SearchRequest
1968 - SearchResponse protocol handshake. Following that, if a sort
1969 criteria was specified as part of the query, a SortRequest -
1970 SortResponse handshake takes place. Note that it is necessary to
1971 perform sorting before any retrieval takes place, so no records will
1972 be returned from the target as part of the SearchResponse because these
1973 would be unsorted. Hence, piggyback is disabled when sort criteria
1974 are set. Following Search - and a possible sort - Retrieval takes
1975 place - as one or more Present Requests/Response pairs being
1979 The API allows for two different modes for retrieval. A high level
1980 mode which is somewhat more powerful and a low level one.
1981 The low level is enabled when searching on a Connection object
1982 for which the settings
1983 <literal>smallSetUpperBound</literal>,
1984 <literal>mediumSetPresentNumber</literal> and
1985 <literal>largeSetLowerBound</literal> are set. The low level mode
1986 thus allows you to precisely set how records are returned as part
1987 of a search response as offered by the Z39.50 protocol.
1988 Since the client may be retrieving records as part of the
1989 search response, this mode doesn't work well if sorting is used.
1992 The high-level mode allows you to fetch a range of records from
1993 the result set with a given start offset. When you use this mode
1994 the client will automatically use piggyback if that is possible
1995 with the target and perform one or more present requests as needed.
1996 Even if the target returns fewer records as part of a present response
1997 because of a record size limit, etc. the client will repeat sending
1998 present requests. As an example, if option <literal>start</literal>
1999 is 0 (default) and <literal>count</literal> is 4, and
2000 <literal>piggyback</literal> is 1 (default) and no sorting criteria
2001 is specified, then the client will attempt to retrieve the 4
2002 records as part the search response (using piggyback). On the other
2003 hand, if either <literal>start</literal> is positive or if
2004 a sorting criteria is set, or if <literal>piggyback</literal>
2005 is 0, then the client will not perform piggyback but send Present
2009 If either of the options <literal>mediumSetElementSetName</literal> and
2010 <literal>smallSetElementSetName</literal> are unset, the value
2011 of option <literal>elementSetName</literal> is used for piggyback
2012 searches. This means that for the high-level mode you only have
2013 to specify one elementSetName option rather than three.
2016 <sect2 id="zoom.sru.resultset.behavior">
2017 <title>SRU Protocol behavior</title>
2019 Current version of &yaz; does not take advantage of a result set id
2020 returned by the SRU server. Future versions might do, however.
2021 Since, the ZOOM driver does not save result set IDs any
2022 present (retrieval) is transformed to a SRU SearchRetrieveRequest
2023 with same query but, possibly, different offsets.
2026 Option <literal>schema</literal> specifies SRU schema
2027 for retrieval. However, options <literal>elementSetName</literal> and
2028 <literal>preferredRecordSyntax</literal> are ignored.
2031 Options <literal>start</literal> and <literal>count</literal>
2032 are supported by SRU.
2033 The remaining options
2034 <literal>piggyback</literal>,
2035 <literal>smallSetUpperBound</literal>,
2036 <literal>largeSetLowerBound</literal>,
2037 <literal>mediumSetPresentNumber</literal>,
2038 <literal>mediumSetElementSetName</literal>,
2039 <literal>smallSetElementSetName</literal> are
2043 SRU supports CQL queries, <emphasis>not</emphasis> PQF.
2044 If PQF is used, however, the PQF query is transferred anyway
2045 using non-standard element <literal>pQuery</literal> in
2046 SRU SearchRetrieveRequest.
2049 Solr queries has to be done in Solr query format.
2052 Unfortunately, SRU or Solr does not define a database setting. Hence,
2053 <literal>databaseName</literal> is unsupported and ignored.
2054 However, the path part in host parameter for functions
2055 <function>ZOOM_connecton_new</function> and
2056 <function>ZOOM_connection_connect</function> acts as a
2057 database (at least for the &yaz; SRU server).
2061 <sect1 id="zoom.records">
2062 <title>Records</title>
2064 A record object is a retrieval record on the client side -
2065 created from result sets.
2068 void ZOOM_resultset_records(ZOOM_resultset r,
2070 size_t start, size_t count);
2071 ZOOM_record ZOOM_resultset_record(ZOOM_resultset s, size_t pos);
2073 const char *ZOOM_record_get(ZOOM_record rec, const char *type,
2076 int ZOOM_record_error(ZOOM_record rec, const char **msg,
2077 const char **addinfo, const char **diagset);
2079 ZOOM_record ZOOM_record_clone(ZOOM_record rec);
2081 void ZOOM_record_destroy(ZOOM_record rec);
2084 References to temporary records are returned by functions
2085 <function>ZOOM_resultset_records</function> or
2086 <function>ZOOM_resultset_record</function>.
2089 If a persistent reference to a record is desired
2090 <function>ZOOM_record_clone</function> should be used.
2091 It returns a record reference that should be destroyed
2092 by a call to <function>ZOOM_record_destroy</function>.
2095 A single record is returned by function
2096 <function>ZOOM_resultset_record</function> that takes a
2097 position as argument. First record has position zero.
2098 If no record could be obtained <literal>NULL</literal> is returned.
2101 Error information for a record can be checked with
2102 <function>ZOOM_record_error</function> which returns non-zero
2103 (error code) if record is in error, called <emphasis>Surrogate
2104 Diagnostics</emphasis> in Z39.50.
2107 Function <function>ZOOM_resultset_records</function> retrieves
2108 a number of records from a result set. Parameter <literal>start</literal>
2109 and <literal>count</literal> specifies the range of records to
2110 be returned. Upon completion array
2111 <literal>recs[0], ..recs[count-1]</literal>
2112 holds record objects for the records. The array of records
2113 <literal>recs</literal> should be allocated prior the call
2114 <function>ZOOM_resultset_records</function>. Note that for those
2115 records that couldn't be retrieved from the target
2116 <literal>recs[ ..]</literal> is set to <literal>NULL</literal>.
2118 <para id="zoom.record.get">
2119 In order to extract information about a single record,
2120 <function>ZOOM_record_get</function> is provided. The
2121 function returns a pointer to certain record information. The
2122 nature (type) of the pointer depends on the parameter,
2123 <parameter>type</parameter>.
2126 The <parameter>type</parameter> is a string of the format:
2129 <replaceable>format</replaceable>[;charset=<replaceable>from</replaceable>[/<replaceable>opacfrom</replaceable>][,<replaceable>to</replaceable>]][;format=<replaceable>v</replaceable>][;base64=<replaceable>xpath</replaceable>]
2132 If <literal>charset</literal> is given, then <replaceable>from</replaceable>
2133 specifies the character set of the record in its original form
2134 (as returned by the server), <replaceable>to</replaceable> specifies
2135 the output (returned) character set encoding.
2136 If <replaceable>to</replaceable> is omitted, then UTF-8 is assumed.
2137 If charset is not given, then no character set conversion takes place.
2138 OPAC records may be returned in a different
2139 set from the bibliographic MARC record. If this is this the case,
2140 <replaceable>opacfrom</replaceable> should be set to the character set
2141 of the OPAC record part.
2145 The <literal>format</literal> is generic but can only be used to
2146 specify XML indentation when the value <replaceable>v</replaceable>
2147 is 1 (<literal>format=1</literal>).
2150 The <literal>base64</literal> allows a full record to be extracted
2151 from base64-encoded string in an XML document.
2155 Specifying the OPAC record character set requires YAZ 4.1.5 or later.
2158 Specifying the base64 parameter requires YAZ 4.2.35 or later.
2162 The format argument controls whether record data should be XML
2163 pretty-printed (post process operation).
2164 It is enabled only if format value <replaceable>v</replaceable> is
2165 <literal>1</literal> and the record content is XML well-formed.
2168 In addition, for certain types, the length
2169 <literal>len</literal> passed will be set to the size in bytes of
2170 the returned information.
2173 The following are the supported values for <replaceable>form</replaceable>.
2175 <varlistentry><term><literal>database</literal></term>
2176 <listitem><para>Database of record is returned
2177 as a C null-terminated string. Return type
2178 <literal>const char *</literal>.
2181 <varlistentry><term><literal>syntax</literal></term>
2182 <listitem><para>The transfer syntax of the record is returned
2183 as a C null-terminated string containing the symbolic name of
2184 the record syntax, e.g. <literal>Usmarc</literal>. Return type
2186 <literal>const char *</literal>.
2189 <varlistentry><term><literal>schema</literal></term>
2190 <listitem><para>The schema of the record is returned
2191 as a C null-terminated string. Return type is
2192 <literal>const char *</literal>.
2195 <varlistentry><term><literal>render</literal></term>
2196 <listitem><para>The record is returned in a display friendly
2197 format. Upon completion buffer is returned
2198 (type <literal>const char *</literal>) and length is stored in
2199 <literal>*len</literal>.
2202 <varlistentry><term><literal>raw</literal></term>
2203 <listitem><para>The record is returned in the internal
2204 YAZ specific format. For GRS-1, Explain, and others, the
2205 raw data is returned as type
2206 <literal>Z_External *</literal> which is just the type for
2207 the member <literal>retrievalRecord</literal> in
2208 type <literal>NamePlusRecord</literal>.
2209 For SUTRS and octet aligned record (including all MARCs) the
2210 octet buffer is returned and the length of the buffer.
2213 <varlistentry><term><literal>xml</literal></term>
2214 <listitem><para>The record is returned in XML if possible.
2215 SRU, Solr and Z39.50 records with transfer syntax XML are
2216 returned verbatim. MARC records are returned in
2217 <ulink url="&url.marcxml;">
2220 (converted from ISO2709 to MARCXML by YAZ).
2221 OPAC records are also converted to XML and the
2222 bibliographic record is converted to MARCXML (when possible).
2223 GRS-1 records are not supported for this form.
2224 Upon completion, the XML buffer is returned
2225 (type <literal>const char *</literal>) and length is stored in
2226 <literal>*len</literal>.
2229 <varlistentry><term><literal>opac</literal></term>
2230 <listitem><para>OPAC information for record is returned in XML
2231 if an OPAC record is present at the position given. If no
2232 OPAC record is present, a NULL pointer is returned.
2235 <varlistentry><term><literal>txml</literal></term>
2236 <listitem><para>The record is returned in TurboMARC if possible.
2237 SRU and Z39.50 records with transfer syntax XML are
2238 returned verbatim. MARC records are returned in
2239 <link linkend="tools.turbomarc">
2242 (converted from ISO2709 to TurboMARC by YAZ).
2243 Upon completion, the XML buffer is returned
2244 (type <literal>const char *</literal>) and length is stored in
2245 <literal>*len</literal>.
2248 <varlistentry><term><literal>json</literal></term>
2249 <listitem><para>Like xml, but MARC records are converted to
2250 <ulink url="&url.marc_in_json;">MARC-in-JSON</ulink>.
2258 <ulink url="&url.marc21;">MARC21</ulink>
2260 <ulink url="&url.marc8;">MARC-8</ulink>
2261 character set encoding.
2262 An application that wishes to display in Latin-1 would use
2264 render; charset=marc8,iso-8859-1
2267 <sect2 id="zoom.z3950.record.behavior">
2268 <title>Z39.50 Protocol behavior</title>
2270 The functions <function>ZOOM_resultset_record</function> and
2271 <function>ZOOM_resultset_records</function> inspects the client-side
2272 record cache. Records not found in cache are fetched using
2274 The functions may block (and perform network I/O) - even though option
2275 <literal>async</literal> is 1, because they return records objects.
2276 (and there's no way to return records objects without retrieving them!).
2279 There is a trick, however, in the usage of function
2280 <function>ZOOM_resultset_records</function> that allows for
2281 delayed retrieval (and makes it non-blocking). By using
2282 a null pointer for <parameter>recs</parameter> you're indicating
2283 you're not interested in getting records objects
2284 <emphasis>now</emphasis>.
2287 <sect2 id="zoom.sru.record.behavior">
2288 <title>SRU/Solr Protocol behavior</title>
2290 The ZOOM driver for SRU/Solr treats records returned by a SRU/Solr server
2291 as if they where Z39.50 records with transfer syntax XML and
2292 no element set name or database name.
2296 <sect1 id="zoom.facets"><title>Facets</title>
2298 Facet operations is not part of the official ZOOM specification, but
2299 is an Index Data extension for YAZ-based Z39.50 targets,
2300 <ulink url="&url.solr;">Solr</ulink> and SRU 2.0 targets.
2302 Facets may be requestd by the
2303 <link linkend="zoom.facets.option">facets</link> option before a
2305 For inspection of the returned facets, the following functions are
2309 ZOOM_facet_field *ZOOM_resultset_facets(ZOOM_resultset r);
2311 ZOOM_facet_field ZOOM_resultset_get_facet_field(ZOOM_resultset r,
2312 const char *facet_name);
2314 ZOOM_facet_field ZOOM_resultset_get_facet_field_by_index(ZOOM_resultset r,
2317 size_t ZOOM_resultset_facets_size(ZOOM_resultset r);
2319 const char *ZOOM_facet_field_name(ZOOM_facet_field facet_field);
2321 size_t ZOOM_facet_field_term_count(ZOOM_facet_field facet_field);
2323 const char *ZOOM_facet_field_get_term(ZOOM_facet_field facet_field,
2324 size_t idx, int *freq);
2327 References to temporary structures are returned by all functions.
2328 They are only valid as long the Result set is valid.
2329 <function>ZOOM_resultset_get_facet_field</function> or
2330 <function>ZOOM_resultset_get_facet_field_by_index</function>.
2331 <function>ZOOM_resultset_facets</function>.
2332 <function>ZOOM_facet_field_name</function>.
2333 <function>ZOOM_facet_field_get_term</function>.
2335 <para id="zoom.resultset.get_facet_field">
2336 A single Facet field is returned by function
2337 <function>ZOOM_resultset_get_facet_field</function> or
2338 <function>ZOOM_resultset_get_facet_field_by_index</function> that takes
2339 a result set and facet name or positive index respectively. First
2340 facet has position zero. If no facet could be obtained (invalid name
2341 or index out of bounds) <literal>NULL</literal> is returned.
2343 <para id="zoom.resultset.facets">
2344 An array of facets field can be returned by
2345 <function>ZOOM_resultset_facets</function>. The length of the array is
2346 given by <function>ZOOM_resultset_facets_size</function>. The array is
2347 zero-based and last entry will be at
2348 <function>ZOOM_resultset_facets_size(result_set)</function>-1.
2350 <para id="zoom.resultset.facets_names">
2351 It is possible to interate over facets by name, by calling
2352 <function>ZOOM_resultset_facets_names</function>.
2353 This will return an const array of char * where each string can be used
2354 as parameter for <function>ZOOM_resultset_get_facet_field</function>.
2357 Function <function>ZOOM_facet_field_name</function> gets the request
2358 facet name from a returned facet field.
2361 Function <function>ZOOM_facet_field_get_term</function> returns the
2362 idx'th term and term count for a facet field.
2363 Idx must between 0 and
2364 <function>ZOOM_facet_field_term_count</function>-1, otherwise the
2365 returned reference will be <literal>NULL</literal>. On a valid idx, the
2366 value of the freq reference will be the term count.
2367 The <literal>freq</literal> parameter must be valid pointer to integer.
2370 <sect1 id="zoom.scan"><title>Scan</title>
2372 This section describes an interface for Scan. Scan is not an
2373 official part of the ZOOM model yet. The result of a scan operation
2374 is the <literal>ZOOM_scanset</literal> which is a set of terms
2375 returned by a target.
2379 The Scan interface is supported for both Z39.50, SRU and Solr.
2383 ZOOM_scanset ZOOM_connection_scan(ZOOM_connection c,
2384 const char *startpqf);
2386 ZOOM_scanset ZOOM_connection_scan1(ZOOM_connection c,
2389 size_t ZOOM_scanset_size(ZOOM_scanset scan);
2391 const char *ZOOM_scanset_term(ZOOM_scanset scan, size_t pos,
2392 size_t *occ, size_t *len);
2394 const char *ZOOM_scanset_display_term(ZOOM_scanset scan, size_t pos,
2395 size_t *occ, size_t *len);
2397 void ZOOM_scanset_destroy(ZOOM_scanset scan);
2399 const char *ZOOM_scanset_option_get(ZOOM_scanset scan,
2402 void ZOOM_scanset_option_set(ZOOM_scanset scan, const char *key,
2406 The scan set is created by function
2407 <function>ZOOM_connection_scan</function> which performs a scan
2408 operation on the connection using the specified
2409 <parameter>startpqf</parameter>.
2410 If the operation was successful, the size of the scan set can be
2411 retrieved by a call to <function>ZOOM_scanset_size</function>.
2412 Like result sets, the items are numbered 0,..size-1.
2413 To obtain information about a particular scan term, call function
2414 <function>ZOOM_scanset_term</function>. This function takes
2415 a scan set offset <literal>pos</literal> and returns a pointer
2416 to a <emphasis>raw term</emphasis> or <literal>NULL</literal> if
2418 If present, the <literal>occ</literal> and <literal>len</literal>
2419 are set to the number of occurrences and the length
2420 of the actual term respectively.
2421 <function>ZOOM_scanset_display_term</function> is similar to
2422 <function>ZOOM_scanset_term</function> except that it returns
2423 the <emphasis>display term</emphasis> rather than the raw term.
2424 In a few cases, the term is different from display term. Always
2425 use the display term for display and the raw term for subsequent
2426 scan operations (to get more terms, next scan result, etc).
2429 A scan set may be freed by a call to function
2430 <function>ZOOM_scanset_destroy</function>.
2431 Functions <function>ZOOM_scanset_option_get</function> and
2432 <function>ZOOM_scanset_option_set</function> retrieves and sets
2433 an option respectively.
2436 The <parameter>startpqf</parameter> is a subset of PQF, namely
2437 the Attributes+Term part. Multiple <literal>@attr</literal> can
2438 be used. For example to scan in title (complete) phrases:
2440 @attr 1=4 @attr 6=2 "science o"
2444 The <function>ZOOM_connecton_scan1</function> is a newer and
2445 more generic alternative to <function>ZOOM_connection_scan</function>
2446 which allows to use both CQL and PQF for Scan.
2448 <table frame="top" id="zoom.scanset.options">
2449 <title>ZOOM Scan Set Options</title>
2451 <colspec colwidth="4*" colname="name"></colspec>
2452 <colspec colwidth="7*" colname="description"></colspec>
2453 <colspec colwidth="2*" colname="default"></colspec>
2456 <entry>Option</entry>
2457 <entry>Description</entry>
2458 <entry>Default</entry>
2463 number</entry><entry>Number of Scan Terms requested in next scan.
2464 After scan it holds the actual number of terms returned.
2465 </entry><entry>20</entry></row>
2467 position</entry><entry>Preferred Position of term in response
2468 in next scan; actual position after completion of scan.
2469 </entry><entry>1</entry></row>
2471 stepSize</entry><entry>Step Size
2472 </entry><entry>0</entry></row>
2474 scanStatus</entry><entry>An integer indicating the Scan Status
2476 </entry><entry>0</entry></row>
2478 rpnCharset</entry><entry>Character set for RPN terms.
2479 If this is set, ZOOM C will assume that the ZOOM application is
2480 running UTF-8. Terms in RPN queries are then converted to the
2481 rpnCharset. If this is unset, ZOOM C will not assume any encoding
2482 of RPN terms and no conversion is performed.
2483 </entry><entry>none</entry></row>
2488 <sect1 id="zoom.extendedservices">
2489 <title>Extended Services</title>
2491 ZOOM offers an interface to a subset of the Z39.50 extended services
2492 as well as a few privately defined ones:
2497 Z39.50 Item Order (ILL).
2498 See <xref linkend="zoom.item.order"/>.
2503 Record Update. This allows a client to insert, modify or delete
2505 See <xref linkend="zoom.record.update"/>.
2510 Database Create. This a non-standard feature. Allows a client
2511 to create a database.
2512 See <xref linkend="zoom.database.create"/>.
2517 Database Drop. This a non-standard feature. Allows a client
2518 to delete/drop a database.
2519 See <xref linkend="zoom.database.drop"/>.
2524 Commit operation. This a non-standard feature. Allows a client
2525 to commit operations.
2526 See <xref linkend="zoom.commit"/>.
2529 <!-- all the ILL PDU options should go here too -->
2532 To create an extended service operation a <literal>ZOOM_package</literal>
2533 must be created. The operation is a five step operation. The
2534 package is created, package is configured by means of options,
2535 the package is send, result is inspected (by means of options),
2536 the package is destroyed.
2539 ZOOM_package ZOOM_connection_package(ZOOM_connection c,
2540 ZOOM_options options);
2542 const char *ZOOM_package_option_get(ZOOM_package p,
2544 void ZOOM_package_option_set(ZOOM_package p, const char *key,
2546 void ZOOM_package_send(ZOOM_package p, const char *type);
2548 void ZOOM_package_destroy(ZOOM_package p);
2551 The <function>ZOOM_connection_package</function> creates a
2552 package for the connection given using the options specified.
2555 Functions <function>ZOOM_package_option_get</function> and
2556 <function>ZOOM_package_option_set</function> gets and sets
2560 <function>ZOOM_package_send</function> sends
2561 the package the via connection specified in
2562 <function>ZOOM_connection_package</function>.
2563 The <parameter>type</parameter> specifies the actual extended service
2564 package type to be sent.
2566 <table frame="top" id="zoom.extendedservices.options">
2567 <title>Extended Service Common Options</title>
2569 <colspec colwidth="4*" colname="name"></colspec>
2570 <colspec colwidth="7*" colname="description"></colspec>
2571 <colspec colwidth="3*" colname="default"></colspec>
2574 <entry>Option</entry>
2575 <entry>Description</entry>
2576 <entry>Default</entry>
2581 <entry>package-name</entry>
2582 <entry>Extended Service Request package name. Must be specified
2583 as part of a request</entry>
2587 <entry>user-id</entry>
2588 <entry>User ID of Extended Service Package. Is a request option</entry>
2592 <entry>function</entry>
2594 Function of package - one of <literal>create</literal>,
2595 <literal>delete</literal>, <literal>modify</literal>. Is
2598 <entry><literal>create</literal></entry>
2601 <entry>waitAction</entry>
2603 Wait action for package. Possible values:
2604 <literal>wait</literal>, <literal>waitIfPossible</literal>,
2605 <literal>dontWait</literal> or <literal>dontReturnPackage</literal>.
2607 <entry><literal>waitIfPossible</literal></entry>
2610 <entry>targetReference</entry>
2612 Target Reference. This is part of the response as returned
2613 by the server. Read it after a successful operation.
2615 <entry><literal>none</literal></entry>
2620 <sect2 id="zoom.item.order">
2621 <title>Item Order</title>
2623 For Item Order, type must be set to <literal>itemorder</literal> in
2624 <function>ZOOM_package_send</function>.
2627 <table frame="top" id="zoom.item.order.options">
2628 <title>Item Order Options</title>
2630 <colspec colwidth="4*" colname="name"></colspec>
2631 <colspec colwidth="7*" colname="description"></colspec>
2632 <colspec colwidth="3*" colname="default"></colspec>
2635 <entry>Option</entry>
2636 <entry>Description</entry>
2637 <entry>Default</entry>
2642 <entry>contact-name</entry>
2643 <entry>ILL contact name</entry>
2647 <entry>contact-phone</entry>
2648 <entry>ILL contact phone</entry>
2652 <entry>contact-email</entry>
2653 <entry>ILL contact email</entry>
2657 <entry>itemorder-item</entry>
2658 <entry>Position for item (record) requested. An integer</entry>
2665 <sect2 id="zoom.record.update">
2666 <title>Record Update</title>
2668 For Record Update, type must be set to <literal>update</literal> in
2669 <function>ZOOM_package_send</function>.
2671 <table frame="top" id="zoom.record.update.options">
2672 <title>Record Update Options</title>
2674 <colspec colwidth="4*" colname="name"></colspec>
2675 <colspec colwidth="7*" colname="description"></colspec>
2676 <colspec colwidth="3*" colname="default"></colspec>
2679 <entry>Option</entry>
2680 <entry>Description</entry>
2681 <entry>Default</entry>
2686 <entry>action</entry>
2688 The update action. One of
2689 <literal>specialUpdate</literal>,
2690 <literal>recordInsert</literal>,
2691 <literal>recordReplace</literal>,
2692 <literal>recordDelete</literal>,
2693 <literal>elementUpdate</literal>.
2695 <entry><literal>specialUpdate (recordInsert for updateVersion=1 which does not support specialUpdate)</literal></entry>
2698 <entry>recordIdOpaque</entry>
2699 <entry>Opaque Record ID</entry>
2703 <entry>recordIdNumber</entry>
2704 <entry>Record ID number</entry>
2708 <entry>record</entry>
2709 <entry>The record itself</entry>
2713 <entry>recordOpaque</entry>
2714 <entry>Specifies an opaque record which is
2715 encoded as an ASN.1 ANY type with the OID as tiven by option
2716 <literal>syntax</literal> (see below).
2717 Option <literal>recordOpaque</literal> is an alternative
2718 to record - and <literal>record</literal> option (above) is
2719 ignored if recordOpaque is set. This option is only available in
2720 YAZ 3.0.35 and later and is meant to facilitate Updates with
2726 <entry>syntax</entry>
2727 <entry>The record syntax (transfer syntax). Is a string that
2728 is a known record syntax.
2730 <entry>no syntax</entry>
2733 <entry>databaseName</entry>
2734 <entry>Database from connection object</entry>
2735 <entry>Default</entry>
2738 <entry>correlationInfo.note</entry>
2739 <entry>Correlation Info Note (string)</entry>
2743 <entry>correlationInfo.id</entry>
2744 <entry>Correlation Info ID (integer)</entry>
2748 <entry>elementSetName</entry>
2749 <entry>Element Set for Record</entry>
2753 <entry>updateVersion</entry>
2754 <entry>Record Update version which holds one of the values
2755 1, 2 or 3. Each version has a distinct OID:
2757 (<ulink url="&url.z39.50.extupdate1;">first version</ulink>) ,
2759 (second version) and
2760 1.2.840.10003.9.5.1.1
2761 (<ulink url="&url.z39.50.extupdate3;">third and
2762 newest version</ulink>).
2772 <sect2 id="zoom.database.create"><title>Database Create</title>
2774 For Database Create, type must be set to <literal>create</literal> in
2775 <function>ZOOM_package_send</function>.
2778 <table frame="top" id="zoom.database.create.options">
2779 <title>Database Create Options</title>
2781 <colspec colwidth="4*" colname="name"></colspec>
2782 <colspec colwidth="7*" colname="description"></colspec>
2783 <colspec colwidth="3*" colname="default"></colspec>
2786 <entry>Option</entry>
2787 <entry>Description</entry>
2788 <entry>Default</entry>
2793 <entry>databaseName</entry>
2794 <entry>Database from connection object</entry>
2795 <entry>Default</entry>
2801 <sect2 id="zoom.database.drop">
2802 <title>Database Drop</title>
2804 For Database Drop, type must be set to <literal>drop</literal> in
2805 <function>ZOOM_package_send</function>.
2807 <table frame="top" id="zoom.database.drop.options">
2808 <title>Database Drop Options</title>
2810 <colspec colwidth="4*" colname="name"></colspec>
2811 <colspec colwidth="7*" colname="description"></colspec>
2812 <colspec colwidth="3*" colname="default"></colspec>
2815 <entry>Option</entry>
2816 <entry>Description</entry>
2817 <entry>Default</entry>
2822 <entry>databaseName</entry>
2823 <entry>Database from connection object</entry>
2824 <entry>Default</entry>
2830 <sect2 id="zoom.commit">
2831 <title>Commit Operation</title>
2833 For Commit, type must be set to <literal>commit</literal> in
2834 <function>ZOOM_package_send</function>.
2837 <sect2 id="zoom.extended.services.behavior">
2838 <title>Protocol behavior</title>
2840 All the extended services are Z39.50-only.
2844 The database create, drop and commit services are privately defined
2846 Refer to <filename>esadmin.asn</filename> in YAZ for the ASN.1
2852 <sect1 id="zoom.options">
2853 <title>Options</title>
2855 Most &zoom; objects provide a way to specify options to change behavior.
2856 From an implementation point of view a set of options is just like
2857 an associative array / hash.
2860 ZOOM_options ZOOM_options_create(void);
2862 ZOOM_options ZOOM_options_create_with_parent(ZOOM_options parent);
2864 void ZOOM_options_destroy(ZOOM_options opt);
2867 const char *ZOOM_options_get(ZOOM_options opt, const char *name);
2869 void ZOOM_options_set(ZOOM_options opt, const char *name,
2873 typedef const char *(*ZOOM_options_callback)
2874 (void *handle, const char *name);
2876 ZOOM_options_callback
2877 ZOOM_options_set_callback(ZOOM_options opt,
2878 ZOOM_options_callback c,
2882 <sect1 id="zoom.queryconversions">
2883 <title>Query conversions</title>
2885 int ZOOM_query_cql2rpn(ZOOM_query s, const char *cql_str,
2886 ZOOM_connection conn);
2888 int ZOOM_query_ccl2rpn(ZOOM_query s, const char *ccl_str,
2890 int *ccl_error, const char **error_string,
2894 <function>ZOOM_query_cql2rpn</function> translates the CQL string,
2895 client-side, into RPN which may be passed to the server.
2896 This is useful for server's that don't themselves
2897 support CQL, for which <function>ZOOM_query_cql</function> is useless.
2898 `conn' is used only as a place to stash diagnostics if compilation
2899 fails; if this information is not needed, a null pointer may be used.
2900 The CQL conversion is driven by option <literal>cqlfile</literal> from
2901 connection conn. This specifies a conversion file (eg pqf.properties)
2902 which <emphasis>must</emphasis> be present.
2905 <function>ZOOM_query_ccl2rpn</function> translates the CCL string,
2906 client-side, into RPN which may be passed to the server.
2907 The conversion is driven by the specification given by
2908 <literal>config</literal>. Upon completion 0 is returned on success; -1
2909 is returned on on failure. Om failure <literal>error_string</literal> and
2910 <literal>error_pos</literal> holds error message and position of
2911 first error in original CCL string.
2914 <sect1 id="zoom.events"><title>Events</title>
2916 If you're developing non-blocking applications, you have to deal
2920 int ZOOM_event(int no, ZOOM_connection *cs);
2923 The <function>ZOOM_event</function> executes pending events for
2924 a number of connections. Supply the number of connections in
2925 <literal>no</literal> and an array of connections in
2926 <literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
2927 A pending event could be a sending a search, receiving a response,
2929 When an event has occurred for one of the connections, this function
2930 returns a positive integer <literal>n</literal> denoting that an event
2931 occurred for connection <literal>cs[n-1]</literal>.
2932 When no events are pending for the connections, a value of zero is
2934 To ensure that all outstanding requests are performed call this function
2935 repeatedly until zero is returned.
2938 If <function>ZOOM_event</function> returns and returns non-zero, the
2939 last event that occurred can be expected.
2942 int ZOOM_connection_last_event(ZOOM_connection cs);
2945 <function>ZOOM_connection_last_event</function> returns an event type
2946 (integer) for the last event.
2949 <table frame="top" id="zoom.event.ids">
2950 <title>ZOOM Event IDs</title>
2952 <colspec colwidth="4*" colname="name"></colspec>
2953 <colspec colwidth="7*" colname="description"></colspec>
2956 <entry>Event</entry>
2957 <entry>Description</entry>
2962 <entry>ZOOM_EVENT_NONE</entry>
2963 <entry>No event has occurred</entry>
2966 <entry>ZOOM_EVENT_CONNECT</entry>
2967 <entry>TCP/IP connect has initiated</entry>
2970 <entry>ZOOM_EVENT_SEND_DATA</entry>
2971 <entry>Data has been transmitted (sending)</entry>
2974 <entry>ZOOM_EVENT_RECV_DATA</entry>
2975 <entry>Data has been received)</entry>
2978 <entry>ZOOM_EVENT_TIMEOUT</entry>
2979 <entry>Timeout</entry>
2982 <entry>ZOOM_EVENT_UNKNOWN</entry>
2983 <entry>Unknown event</entry>
2986 <entry>ZOOM_EVENT_SEND_APDU</entry>
2987 <entry>An APDU has been transmitted (sending)</entry>
2990 <entry>ZOOM_EVENT_RECV_APDU</entry>
2991 <entry>An APDU has been received</entry>
2994 <entry>ZOOM_EVENT_RECV_RECORD</entry>
2995 <entry>A result-set record has been received</entry>
2998 <entry>ZOOM_EVENT_RECV_SEARCH</entry>
2999 <entry>A search result been received</entry>
3006 <chapter id="server">
3007 <title>Generic server</title>
3008 <sect1 id="server.introduction"><title>Introduction</title>
3010 If you aren't into documentation, a good way to learn how the
3011 back end interface works is to look at the <filename>backend.h</filename>
3012 file. Then, look at the small dummy-server in
3013 <filename>ztest/ztest.c</filename>. The <filename>backend.h</filename>
3014 file also makes a good reference, once you've chewed your way through
3015 the prose of this file.
3018 If you have a database system that you would like to make available by
3019 means of Z39.50 or SRU, &yaz; basically offers your two options. You
3020 can use the APIs provided by the &asn;, &odr;, and &comstack;
3022 create and decode PDUs, and exchange them with a client.
3023 Using this low-level interface gives you access to all fields and
3024 options of the protocol, and you can construct your server as close
3025 to your existing database as you like.
3026 It is also a fairly involved process, requiring
3027 you to set up an event-handling mechanism, protocol state machine,
3028 etc. To simplify server implementation, we have implemented a compact
3029 and simple, but reasonably full-functioned server-frontend that will
3030 handle most of the protocol mechanics, while leaving you to
3031 concentrate on your database interface.
3035 The backend interface was designed in anticipation of a specific
3036 integration task, while still attempting to achieve some degree of
3037 generality. We realize fully that there are points where the
3038 interface can be improved significantly. If you have specific
3039 functions or parameters that you think could be useful, send us a
3040 mail (or better, sign on to the mailing list referred to in the
3041 top-level README file). We will try to fit good suggestions into future
3042 releases, to the extent that it can be done without requiring
3043 too many structural changes in existing applications.
3048 The &yaz; server does not support XCQL.
3052 <sect1 id="server.frontend">
3053 <title>The Database Frontend</title>
3055 We refer to this software as a generic database frontend. Your
3056 database system is the <emphasis>backend database</emphasis>, and the
3057 interface between the two is called the <emphasis>backend API</emphasis>.
3058 The backend API consists of a small number of function handlers and
3059 structure definitions. You are required to provide the
3060 <function>main()</function> routine for the server (which can be
3061 quite simple), as well as a set of handlers to match each of the
3063 The interface functions that you write can use any mechanism you like
3064 to communicate with your database system: You might link the whole
3065 thing together with your database application and access it by
3066 function calls; you might use IPC to talk to a database server
3067 somewhere; or you might link with third-party software that handles
3068 the communication for you (like a commercial database client library).
3069 At any rate, the handlers will perform the tasks of:
3082 Scanning the database index (optional - if you wish to implement SCAN).
3085 Extended Services (optional).
3088 Result-Set Delete (optional).
3091 Result-Set Sort (optional).
3094 Return Explain for SRU (optional).
3098 (more functions will be added in time to support as much of
3099 Z39.50-1995 as possible).
3102 <sect1 id="server.backend">
3103 <title>The Backend API</title>
3105 The header file that you need to use the interface are in the
3106 <filename>include/yaz</filename> directory. It's called
3107 <filename>backend.h</filename>. It will include other files from
3108 the <filename>include/yaz</filename> directory, so you'll
3109 probably want to use the -I option of your compiler to tell it
3110 where to find the files. When you run
3111 <literal>make</literal> in the top-level &yaz; directory,
3112 everything you need to create your server is to link with the
3113 <filename>lib/libyaz.la</filename> library.
3116 <sect1 id="server.main">
3117 <title>Your main() Routine</title>
3119 As mentioned, your <function>main()</function> routine can be quite brief.
3120 If you want to initialize global parameters, or read global configuration
3121 tables, this is the place to do it. At the end of the routine, you should
3125 int statserv_main(int argc, char **argv,
3126 bend_initresult *(*bend_init)(bend_initrequest *r),
3127 void (*bend_close)(void *handle));
3130 The third and fourth arguments are pointers to handlers. Handler
3131 <function>bend_init</function> is called whenever the server receives
3132 an Initialize Request, so it serves as a Z39.50 session initializer. The
3133 <function>bend_close</function> handler is called when the session is
3137 <function>statserv_main</function> will establish listening sockets
3138 according to the parameters given. When connection requests are received,
3139 the event handler will typically <function>fork()</function> and
3140 create a sub-process to handle a new connection.
3141 Alternatively the server may be setup to create threads for each
3143 If you do use global variables and forking, you should be aware, then,
3144 that these cannot be shared between associations, unless you explicitly
3145 disable forking by command line parameters.
3148 The server provides a mechanism for controlling some of its behavior
3149 without using command-line options. The function
3152 statserv_options_block *statserv_getcontrol(void);
3155 will return a pointer to a <literal>struct statserv_options_block</literal>
3156 describing the current default settings of the server. The structure
3157 contains these elements:
3160 <term><literal>int dynamic</literal></term>
3162 A boolean value, which determines whether the server
3163 will fork on each incoming request (TRUE), or not (FALSE). Default is
3164 TRUE. This flag is only read by UNIX-based servers (WIN32 based servers
3169 <term><literal>int threads</literal></term>
3171 A boolean value, which determines whether the server
3172 will create a thread on each incoming request (TRUE), or not (FALSE).
3173 Default is FALSE. This flag is only read by UNIX-based servers
3174 that offer POSIX Threads support.
3175 WIN32-based servers always operate in threaded mode.
3179 <term><literal>int inetd</literal></term>
3181 A boolean value, which determines whether the server
3182 will operates under a UNIX INET daemon (inetd). Default is FALSE.
3186 <term><literal>char logfile[ODR_MAXNAME+1]</literal></term>
3187 <listitem><para>File for diagnostic output ("": stderr).
3191 <term><literal>char apdufile[ODR_MAXNAME+1]</literal></term>
3193 Name of file for logging incoming and outgoing APDUs
3194 ("": don't log APDUs, "-":
3195 <literal>stderr</literal>).
3199 <term><literal>char default_listen[1024]</literal></term>
3200 <listitem><para>Same form as the command-line specification of
3201 listener address. "": no default listener address.
3202 Default is to listen at "tcp:@:9999". You can only
3203 specify one default listener address in this fashion.
3207 <term><literal>enum oid_proto default_proto;</literal></term>
3208 <listitem><para>Either <literal>PROTO_Z3950</literal> or
3209 <literal>PROTO_SR</literal>.
3210 Default is <literal>PROTO_Z39_50</literal>.
3214 <term><literal>int idle_timeout;</literal></term>
3215 <listitem><para>Maximum session idle-time, in minutes. Zero indicates
3216 no (infinite) timeout. Default is 15 minutes.
3220 <term><literal>int maxrecordsize;</literal></term>
3221 <listitem><para>Maximum permissible record (message) size. Default
3222 is 64 MB. This amount of memory will only be allocated if a
3223 client requests a very large amount of records in one operation
3225 Set it to a lower number if you are worried about resource
3226 consumption on your host system.
3230 <term><literal>char configname[ODR_MAXNAME+1]</literal></term>
3231 <listitem><para>Passed to the backend when a new connection is received.
3235 <term><literal>char setuid[ODR_MAXNAME+1]</literal></term>
3236 <listitem><para>Set user id to the user specified, after binding
3237 the listener addresses.
3242 <literal>void (*bend_start)(struct statserv_options_block *p)</literal>
3244 <listitem><para>Pointer to function which is called after the
3245 command line options have been parsed - but before the server
3247 For forked UNIX servers this handler is called in the mother
3248 process; for threaded servers this handler is called in the
3250 The default value of this pointer is NULL in which case it
3251 isn't invoked by the frontend server.
3252 When the server operates as an NT service this handler is called
3253 whenever the service is started.
3258 <literal>void (*bend_stop)(struct statserv_options_block *p)</literal>
3260 <listitem><para>Pointer to function which is called whenever the server
3261 has stopped listening for incoming connections. This function pointer
3262 has a default value of NULL in which case it isn't called.
3263 When the server operates as an NT service this handler is called
3264 whenever the service is stopped.
3268 <term><literal>void *handle</literal></term>
3269 <listitem><para>User defined pointer (default value NULL).
3270 This is a per-server handle that can be used to specify "user-data".
3271 Do not confuse this with the session-handle as returned by bend_init.
3277 The pointer returned by <literal>statserv_getcontrol</literal> points to
3278 a static area. You are allowed to change the contents of the structure,
3279 but the changes will not take effect before you call
3282 void statserv_setcontrol(statserv_options_block *block);
3286 that you should generally update this structure before calling
3287 <function>statserv_main()</function>.
3291 <sect1 id="server.backendfunctions">
3292 <title>The Backend Functions</title>
3294 For each service of the protocol, the backend interface declares one or
3295 two functions. You are required to provide implementations of the
3296 functions representing the services that you wish to implement.
3298 <sect2 id="server.init">
3301 bend_initresult (*bend_init)(bend_initrequest *r);
3304 This handler is called once for each new connection request, after
3305 a new process/thread has been created, and an Initialize Request has
3306 been received from the client. The pointer to the
3307 <function>bend_init</function> handler is passed in the call to
3308 <function>statserv_start</function>.
3311 This handler is also called when operating in SRU mode - when
3312 a connection has been made (even though SRU does not offer
3316 Unlike previous versions of YAZ, the <function>bend_init</function> also
3317 serves as a handler that defines the Z39.50 services that the backend
3318 wish to support. Pointers to <emphasis>all</emphasis> service handlers,
3319 including search - and fetch must be specified here in this handler.
3322 The request - and result structures are defined as
3325 typedef struct bend_initrequest
3327 /** \brief user/name/password to be read */
3328 Z_IdAuthentication *auth;
3329 /** \brief encoding stream (for results) */
3331 /** \brief printing stream */
3333 /** \brief decoding stream (use stream for results) */
3335 /** \brief reference ID */
3336 Z_ReferenceId *referenceId;
3337 /** \brief peer address of client */
3340 /** \brief character set and language negotiation
3342 see include/yaz/z-charneg.h
3344 Z_CharSetandLanguageNegotiation *charneg_request;
3346 /** \brief character negotiation response */
3347 Z_External *charneg_response;
3349 /** \brief character set (encoding) for query terms
3351 This is NULL by default. It should be set to the native character
3352 set that the backend assumes for query terms */
3353 char *query_charset;
3355 /** \brief whehter query_charset also applies to recors
3357 Is 0 (No) by default. Set to 1 (yes) if records is in the same
3358 character set as queries. If in doubt, use 0 (No).
3360 int records_in_same_charset;
3362 char *implementation_id;
3363 char *implementation_name;
3364 char *implementation_version;
3366 /** \brief Z39.50 sort handler */
3367 int (*bend_sort)(void *handle, bend_sort_rr *rr);
3368 /** \brief SRU/Z39.50 search handler */
3369 int (*bend_search)(void *handle, bend_search_rr *rr);
3370 /** \brief SRU/Z39.50 fetch handler */
3371 int (*bend_fetch)(void *handle, bend_fetch_rr *rr);
3372 /** \brief SRU/Z39.50 present handler */
3373 int (*bend_present)(void *handle, bend_present_rr *rr);
3374 /** \brief Z39.50 extended services handler */
3375 int (*bend_esrequest) (void *handle, bend_esrequest_rr *rr);
3376 /** \brief Z39.50 delete result set handler */
3377 int (*bend_delete)(void *handle, bend_delete_rr *rr);
3378 /** \brief Z39.50 scan handler */
3379 int (*bend_scan)(void *handle, bend_scan_rr *rr);
3380 /** \brief Z39.50 segment facility handler */
3381 int (*bend_segment)(void *handle, bend_segment_rr *rr);
3382 /** \brief SRU explain handler */
3383 int (*bend_explain)(void *handle, bend_explain_rr *rr);
3384 /** \brief SRU scan handler */
3385 int (*bend_srw_scan)(void *handle, bend_scan_rr *rr);
3386 /** \brief SRU record update handler */
3387 int (*bend_srw_update)(void *handle, bend_update_rr *rr);
3389 /** \brief whether named result sets are supported (0=disable, 1=enable) */
3390 int named_result_sets;
3393 typedef struct bend_initresult
3395 int errcode; /* 0==OK */
3396 char *errstring; /* system error string or NULL */
3397 void *handle; /* private handle to the backend module */
3401 In general, the server frontend expects that the
3402 <literal>bend_*result</literal> pointer that you return is valid at
3403 least until the next call to a <literal>bend_* function</literal>.
3404 This applies to all of the functions described herein. The parameter
3405 structure passed to you in the call belongs to the server frontend, and
3406 you should not make assumptions about its contents after the current
3407 function call has completed. In other words, if you want to retain any
3408 of the contents of a request structure, you should copy them.
3411 The <literal>errcode</literal> should be zero if the initialization of
3412 the backend went well. Any other value will be interpreted as an error.
3413 The <literal>errstring</literal> isn't used in the current version, but
3414 one option would be to stick it in the initResponse as a VisibleString.
3415 The <literal>handle</literal> is the most important parameter. It should
3416 be set to some value that uniquely identifies the current session to
3417 the backend implementation. It is used by the frontend server in any
3418 future calls to a backend function.
3419 The typical use is to set it to point to a dynamically allocated state
3420 structure that is private to your backend module.
3423 The <literal>auth</literal> member holds the authentication information
3424 part of the Z39.50 Initialize Request. Interpret this if your serves
3425 requires authentication.
3428 The members <literal>peer_name</literal>,
3429 <literal>implementation_id</literal>,
3430 <literal>implementation_name</literal> and
3431 <literal>implementation_version</literal> holds
3432 DNS of client, ID of implementor, name
3433 of client (Z39.50) implementation - and version.
3436 The <literal>bend_</literal> - members are set to NULL when
3437 <function>bend_init</function> is called. Modify the pointers by
3438 setting them to point to backend functions.
3441 <sect2 id="server.search.retrieve">
3442 <title>Search and Retrieve</title>
3444 We now describe the handlers that are required to support search -
3445 and retrieve. You must support two functions - one for search - and one
3446 for fetch (retrieval of one record). If desirable you can provide a
3447 third handler which is called when a present request is received which
3448 allows you to optimize retrieval of multiple-records.
3451 int (*bend_search) (void *handle, bend_search_rr *rr);
3454 char *setname; /* name to give to this set */
3455 int replace_set; /* replace set, if it already exists */
3456 int num_bases; /* number of databases in list */
3457 char **basenames; /* databases to search */
3458 Z_ReferenceId *referenceId;/* reference ID */
3459 Z_Query *query; /* query structure */
3460 ODR stream; /* encode stream */
3461 ODR decode; /* decode stream */
3462 ODR print; /* print stream */
3464 bend_request request;
3465 bend_association association;
3467 int hits; /* number of hits */
3468 int errcode; /* 0==OK */
3469 char *errstring; /* system error string or NULL */
3470 Z_OtherInformation *search_info; /* additional search info */
3471 char *srw_sortKeys; /* holds SRU/SRW sortKeys info */
3472 char *srw_setname; /* holds SRU/SRW generated resultsetID */
3473 int *srw_setnameIdleTime; /* holds SRU/SRW life-time */
3474 int estimated_hit_count; /* if hit count is estimated */
3475 int partial_resultset; /* if result set is partial */
3479 The <function>bend_search</function> handler is a fairly close
3480 approximation of a protocol Z39.50 Search Request - and Response PDUs
3481 The <literal>setname</literal> is the resultSetName from the protocol.
3482 You are required to establish a mapping between the set name and whatever
3483 your backend database likes to use.
3484 Similarly, the <literal>replace_set</literal> is a boolean value
3485 corresponding to the resultSetIndicator field in the protocol.
3486 <literal>num_bases/basenames</literal> is a length of/array of character
3487 pointers to the database names provided by the client.
3488 The <literal>query</literal> is the full query structure as defined in
3489 the protocol ASN.1 specification.
3490 It can be either of the possible query types, and it's up to you to
3491 determine if you can handle the provided query type.
3492 Rather than reproduce the C interface here, we'll refer you to the
3493 structure definitions in the file
3494 <filename>include/yaz/z-core.h</filename>. If you want to look at the
3495 attributeSetId OID of the RPN query, you can either match it against
3496 your own internal tables, or you can use the <link linkend="tools.oid">
3500 The structure contains a number of hits, and an
3501 <literal>errcode/errstring</literal> pair. If an error occurs
3502 during the search, or if you're unhappy with the request, you should
3503 set the errcode to a value from the BIB-1 diagnostic set. The value
3504 will then be returned to the user in a nonsurrogate diagnostic record
3505 in the response. The <literal>errstring</literal>, if provided, will
3506 go in the addinfo field. Look at the protocol definition for the
3507 defined error codes, and the suggested uses of the addinfo field.
3510 The <function>bend_search</function> handler is also called when
3511 the frontend server receives a SRU SearchRetrieveRequest.
3512 For SRU, a CQL query is usually provided by the client.
3513 The CQL query is available as part of <literal>Z_Query</literal>
3514 structure (note that CQL is now part of Z39.50 via an external).
3515 To support CQL in existing implementations that only do Type-1,
3516 we refer to the CQL-to-PQF tool described
3517 <link linkend="cql.to.pqf">here</link>.
3520 To maintain backwards compatibility, the frontend server
3521 of yaz always assume that error codes are BIB-1 diagnostics.
3522 For SRU operation, a Bib-1 diagnostic code is mapped to
3526 int (*bend_fetch) (void *handle, bend_fetch_rr *rr);
3528 typedef struct bend_fetch_rr {
3529 char *setname; /* set name */
3530 int number; /* record number */
3531 Z_ReferenceId *referenceId;/* reference ID */
3532 Odr_oid *request_format; /* format, transfer syntax (OID) */
3533 Z_RecordComposition *comp; /* Formatting instructions */
3534 ODR stream; /* encoding stream - memory source if req */
3535 ODR print; /* printing stream */
3537 char *basename; /* name of database that provided record */
3538 int len; /* length of record or -1 if structured */
3539 char *record; /* record */
3540 int last_in_set; /* is it? */
3541 Odr_oid *output_format; /* response format/syntax (OID) */
3542 int errcode; /* 0==success */
3543 char *errstring; /* system error string or NULL */
3544 int surrogate_flag; /* surrogate diagnostic */
3545 char *schema; /* string record schema input/output */
3549 The frontend server calls the <function>bend_fetch</function> handler
3550 when it needs database records to fulfill a Z39.50 Search Request, a
3551 Z39.50 Present Request or a SRU SearchRetrieveRequest.
3552 The <literal>setname</literal> is simply the name of the result set
3553 that holds the reference to the desired record.
3554 The <literal>number</literal> is the offset into the set (with 1
3555 being the first record in the set). The <literal>format</literal> field
3556 is the record format requested by the client (See
3557 <xref linkend="tools.oid"/>).
3558 A value of NULL for <literal>format</literal> indicates that the
3559 client did not request a specific format.
3560 The <literal>stream</literal> argument is an &odr; stream which
3561 should be used for allocating space for structured data records.
3562 The stream will be reset when all records have been assembled, and
3563 the response package has been transmitted.
3564 For unstructured data, the backend is responsible for maintaining a
3565 static or dynamic buffer for the record between calls.
3568 If a SRU SearchRetrieveRequest is received by the frontend server,
3569 the <literal>referenceId</literal> is NULL and the
3570 <literal>format</literal> (transfer syntax) is the OID for XML.
3571 The schema for SRU is stored in both the
3572 <literal>Z_RecordComposition</literal>
3573 structure and <literal>schema</literal> (simple string).
3576 In the structure, the <literal>basename</literal> is the name of the
3577 database that holds the
3578 record. <literal>len</literal> is the length of the record returned, in
3579 bytes, and <literal>record</literal> is a pointer to the record.
3580 <literal>last_in_set</literal> should be nonzero only if the record
3581 returned is the last one in the given result set.
3582 <literal>errcode</literal> and <literal>errstring</literal>, if
3583 given, will be interpreted as a global error pertaining to the
3584 set, and will be returned in a non-surrogate-diagnostic.
3585 If you wish to return the error as a surrogate-diagnostic
3586 (local error) you can do this by setting
3587 <literal>surrogate_flag</literal> to 1 also.
3590 If the <literal>len</literal> field has the value -1, then
3591 <literal>record</literal> is assumed to point to a constructed data
3592 type. The <literal>format</literal> field will be used to determine
3593 which encoder should be used to serialize the data.
3597 If your backend generates structured records, it should use
3598 <function>odr_malloc()</function> on the provided stream for allocating
3599 data: This allows the frontend server to keep track of the record sizes.
3603 The <literal>format</literal> field is mapped to an object identifier
3604 in the direct reference of the resulting EXTERNAL representation
3609 The current version of &yaz; only supports the direct reference mode.
3613 int (*bend_present) (void *handle, bend_present_rr *rr);
3616 char *setname; /* set name */
3618 int number; /* record number */
3619 Odr_oid *format; /* format, transfer syntax (OID) */
3620 Z_ReferenceId *referenceId;/* reference ID */
3621 Z_RecordComposition *comp; /* Formatting instructions */
3622 ODR stream; /* encoding stream - memory source if required */
3623 ODR print; /* printing stream */
3624 bend_request request;
3625 bend_association association;
3627 int hits; /* number of hits */
3628 int errcode; /* 0==OK */
3629 char *errstring; /* system error string or NULL */
3633 The <function>bend_present</function> handler is called when
3634 the server receives a Z39.50 Present Request.
3635 The <literal>setname</literal>,
3636 <literal>start</literal> and <literal>number</literal> is the
3637 name of the result set - start position - and number of records to
3638 be retrieved respectively. <literal>format</literal> and
3639 <literal>comp</literal> is the preferred transfer syntax and element
3640 specifications of the present request.
3643 Note that this is handler serves as a supplement for
3644 <function>bend_fetch</function> and need not to be defined in order to
3645 support search - and retrieve.
3648 <sect2 id="server.delete">
3649 <title>Delete</title>
3651 For back-ends that supports delete of a result set only one handler
3655 int (*bend_delete)(void *handle, bend_delete_rr *rr);
3657 typedef struct bend_delete_rr {
3661 Z_ReferenceId *referenceId;
3662 int delete_status; /* status for the whole operation */
3663 int *statuses; /* status each set - indexed as setnames */
3670 The delete set function definition is rather primitive, mostly because
3671 we have had no practical need for it as of yet. If someone wants
3672 to provide a full delete service, we'd be happy to add the
3673 extra parameters that are required. Are there clients out there
3674 that will actually delete sets they no longer need?
3678 <sect2 id="server.scan">
3681 For servers that wish to offer the scan service one handler
3685 int (*bend_scan)(void *handle, bend_scan_rr *rr);
3688 BEND_SCAN_SUCCESS, /* ok */
3689 BEND_SCAN_PARTIAL /* not all entries could be found */
3692 typedef struct bend_scan_rr {
3693 int num_bases; /* number of elements in databaselist */
3694 char **basenames; /* databases to search */
3695 Odr_oid *attributeset;
3696 Z_ReferenceId *referenceId; /* reference ID */
3697 Z_AttributesPlusTerm *term;
3698 ODR stream; /* encoding stream - memory source if required */
3699 ODR print; /* printing stream */
3701 int *step_size; /* step size */
3702 int term_position; /* desired index of term in result list/returned */
3703 int num_entries; /* number of entries requested/returned */
3705 /* scan term entries. The called handler does not have
3706 to allocate this. Size of entries is num_entries (see above) */
3707 struct scan_entry *entries;
3708 bend_scan_status status;
3711 char *scanClause; /* CQL scan clause */
3712 char *setname; /* Scan in result set (NULL if omitted) */
3716 This backend server handles both Z39.50 scan
3717 and SRU scan. In order for a handler to distinguish between SRU (CQL) scan
3718 Z39.50 Scan , it must check for a non-NULL value of
3719 <literal>scanClause</literal>.
3723 if designed today, it would be a choice using a union or similar,
3724 but that would break binary compatibility with existing servers.
3729 <sect1 id="server.invocation">
3730 <title>Application Invocation</title>
3732 The finished application has the following
3733 invocation syntax (by way of <function>statserv_main()</function>):
3741 A listener specification consists of a transport mode followed by a
3742 colon (:) followed by a listener address. The transport mode is
3743 either <literal>tcp</literal>, <literal>unix:</literal> or
3744 <literal>ssl</literal>.
3747 For TCP and SSL, an address has the form
3750 hostname | IP-number [: portnumber]
3753 The port number defaults to 210 (standard Z39.50 port).
3756 For UNIX, the address is the filename of socket.
3759 For TCP/IP and SSL, the special hostnames <literal>@</literal>,
3760 maps to <literal>IN6ADDR_ANY_INIT</literal> with
3761 IPV4 binding as well (bindv6only=0),
3762 The special hostname <literal>@4</literal> binds to
3763 <literal>INADDR_ANY</literal> (IPV4 only listener).
3764 The special hostname <literal>@6</literal> binds to
3765 <literal>IN6ADDR_ANY_INIT</literal> with bindv6only=1 (IPV6 only listener).
3767 <example id="server.example.running.unix">
3768 <title>Running the GFS on Unix</title>
3770 Assuming the server application <replaceable>appname</replaceable> is
3771 started as root, the following will make it listen on port 210.
3772 The server will change identity to <literal>nobody</literal>
3773 and write its log to <filename>/var/log/app.log</filename>.
3775 application -l /var/log/app.log -u nobody tcp:@:210
3779 The server will accept Z39.50 requests and offer SRU service on port 210.
3782 <example id="server.example.apache.sru">
3783 <title>Setting up Apache as SRU Frontend</title>
3785 If you use <ulink url="&url.apache;">Apache</ulink>
3786 as your public web server and want to offer HTTP port 80
3787 access to the YAZ server on 210, you can use the
3788 <ulink url="&url.apache.directive.proxypass;">
3789 <literal>ProxyPass</literal></ulink>
3791 If you have virtual host
3792 <literal>srw.mydomain</literal> you can use the following directives
3793 in Apache's httpd.conf:
3796 ErrorLog /home/srw/logs/error_log
3797 TransferLog /home/srw/logs/access_log
3798 ProxyPass / http://srw.mydomain:210/
3803 The above for the Apache 1.3 series.
3806 <example id="server.example.local.access">
3807 <title>Running a server with local access only</title>
3809 Servers that is only being accessed from the local host should listen
3810 on UNIX file socket rather than a Internet socket. To listen on
3811 <filename>/tmp/mysocket</filename> start the server as follows:
3813 application unix:/tmp/mysocket
3818 <sect1 id="server.vhosts">
3819 <title>GFS Configuration and Virtual Hosts</title>
3824 <title>The Z39.50 ASN.1 Module</title>
3825 <sect1 id="asn.introduction">
3826 <title>Introduction</title>
3828 The &asn; module provides you with a set of C struct definitions for the
3829 various PDUs of the Z39.50 protocol, as well as for the complex types
3830 appearing within the PDUs. For the primitive data types, the C
3831 representation often takes the form of an ordinary C language type,
3832 such as <literal>Odr_int</literal> which is equivalent to an integral
3833 C integer. For ASN.1 constructs that have no direct
3834 representation in C, such as general octet strings and bit strings,
3835 the &odr; module (see section <link linkend="odr">The ODR Module</link>)
3836 provides auxiliary definitions.
3839 The &asn; module is located in sub directory <filename>z39.50</filename>.
3840 There you'll find C files that implements encoders and decoders for the
3841 Z39.50 types. You'll also find the protocol definitions:
3842 <filename>z3950v3.asn</filename>, <filename>esupdate.asn</filename>,
3846 <sect1 id="asn.preparing">
3847 <title>Preparing PDUs</title>
3849 A structure representing a complex ASN.1 type doesn't in itself contain the
3850 members of that type. Instead, the structure contains
3851 <emphasis>pointers</emphasis> to the members of the type.
3852 This is necessary, in part, to allow a mechanism for specifying which
3853 of the optional structure (SEQUENCE) members are present, and which
3854 are not. It follows that you will need to somehow provide space for
3855 the individual members of the structure, and set the pointers to
3856 refer to the members.
3859 The conversion routines don't care how you allocate and maintain your
3860 C structures - they just follow the pointers that you provide.
3861 Depending on the complexity of your application, and your personal
3862 taste, there are at least three different approaches that you may take
3863 when you allocate the structures.
3866 You can use static or automatic local variables in the function that
3867 prepares the PDU. This is a simple approach, and it provides the most
3868 efficient form of memory management. While it works well for flat
3869 PDUs like the InitReqest, it will generally not be sufficient for say,
3870 the generation of an arbitrarily complex RPN query structure.
3873 You can individually create the structure and its members using the
3874 <function>malloc(2)</function> function. If you want to ensure that
3875 the data is freed when it is no longer needed, you will have to
3876 define a function that individually releases each member of a
3877 structure before freeing the structure itself.
3880 You can use the <function>odr_malloc()</function> function (see
3881 <xref linkend="odr.use"/> for details). When you use
3882 <function>odr_malloc()</function>, you can release all of the
3883 allocated data in a single operation, independent of any pointers and
3884 relations between the data. <function>odr_malloc()</function> is based on a
3885 "nibble-memory"
3886 scheme, in which large portions of memory are allocated, and then
3887 gradually handed out with each call to <function>odr_malloc()</function>.
3888 The next time you call <function>odr_reset()</function>, all of the
3889 memory allocated since the last call is recycled for future use (actually,
3890 it is placed on a free-list).
3893 You can combine all of the methods described here. This will often be
3894 the most practical approach. For instance, you might use
3895 <function>odr_malloc()</function> to allocate an entire structure and
3896 some of its elements, while you leave other elements pointing to global
3897 or per-session default variables.
3900 The &asn; module provides an important aid in creating new PDUs. For
3901 each of the PDU types (say, <function>Z_InitRequest</function>), a
3902 function is provided that allocates and initializes an instance of
3903 that PDU type for you. In the case of the InitRequest, the function is
3904 simply named <function>zget_InitRequest()</function>, and it sets up
3905 reasonable default value for all of the mandatory members. The optional
3906 members are generally initialized to null pointers. This last aspect
3907 is very important: it ensures that if the PDU definitions are
3908 extended after you finish your implementation (to accommodate
3909 new versions of the protocol, say), you won't get into trouble with
3910 uninitialized pointers in your structures. The functions use
3911 <function>odr_malloc()</function> to
3912 allocate the PDUs and its members, so you can free everything again with a
3913 single call to <function>odr_reset()</function>. We strongly recommend
3914 that you use the <literal>zget_*</literal>
3915 functions whenever you are preparing a PDU (in a C++ API, the
3916 <literal>zget_</literal>
3917 functions would probably be promoted to constructors for the
3921 The prototype for the individual PDU types generally look like this:
3924 Z_<type> *zget_<type>(ODR o);
3930 Z_InitRequest *zget_InitRequest(ODR o);
3933 The &odr; handle should generally be your encoding stream, but it
3937 As well as the individual PDU functions, a function
3938 <function>zget_APDU()</function> is provided, which allocates
3939 a top-level Z-APDU of the type requested:
3942 Z_APDU *zget_APDU(ODR o, int which);
3945 The <varname>which</varname> parameter is (of course) the discriminator
3946 belonging to the <varname>Z_APDU</varname> <literal>CHOICE</literal> type.
3947 All of the interface described here is provided by the &asn; module, and
3948 you access it through the <filename>proto.h</filename> header file.
3951 <sect1 id="asn.external">
3952 <title>EXTERNAL Data</title>
3954 In order to achieve extensibility and adaptability to different
3955 application domains, the new version of the protocol defines many
3956 structures outside of the main ASN.1 specification, referencing them
3957 through ASN.1 EXTERNAL constructs. To simplify the construction and
3958 access to the externally referenced data, the &asn; module defines a
3959 specialized version of the EXTERNAL construct, called
3960 <literal>Z_External</literal>.It is defined thus:
3963 typedef struct Z_External
3965 Odr_oid *direct_reference;
3966 int *indirect_reference;
3971 Z_External_single = 0,
3973 Z_External_arbitrary,
3975 /* Specific types */
3977 Z_External_explainRecord,
3978 Z_External_resourceReport1,
3979 Z_External_resourceReport2
3987 Odr_any *single_ASN1_type;
3988 Odr_oct *octet_aligned;
3989 Odr_bitmask *arbitrary;
3991 /* Specific types */
3993 Z_ExplainRecord *explainRecord;
3994 Z_ResourceReport1 *resourceReport1;
3995 Z_ResourceReport2 *resourceReport2;
4003 When decoding, the &asn; module will attempt to determine which
4004 syntax describes the data by looking at the reference fields
4005 (currently only the direct-reference). For ASN.1 structured data, you
4006 need only consult the <literal>which</literal> field to determine the
4007 type of data. You can the access the data directly through the union.
4008 When constructing data for encoding, you set the union pointer to point
4009 to the data, and set the <literal>which</literal> field accordingly.
4010 Remember also to set the direct (or indirect) reference to the correct
4011 OID for the data type.
4012 For non-ASN.1 data such as MARC records, use the
4013 <literal>octet_aligned</literal> arm of the union.
4016 Some servers return ASN.1 structured data values (eg. database
4017 records) as BER-encoded records placed in the
4018 <literal>octet-aligned</literal> branch of the EXTERNAL CHOICE.
4019 The ASN-module will <emphasis>not</emphasis> automatically decode
4020 these records. To help you decode the records in the application, the
4024 Z_ext_typeent *z_ext_gettypebyref(const oid *oid);
4027 Can be used to retrieve information about the known, external data
4028 types. The function return a pointer to a static area, or NULL, if no
4029 match for the given direct reference is found. The
4030 <literal>Z_ext_typeent</literal>
4034 typedef struct Z_ext_typeent
4036 int oid[OID_SIZE]; /* the direct-reference OID. */
4037 int what; /* discriminator value for the external CHOICE */
4038 Odr_fun fun; /* decoder function */
4042 The <literal>what</literal> member contains the
4043 <literal>Z_External</literal> union discriminator value for the
4044 given type: For the SUTRS record syntax, the value would be
4045 <literal>Z_External_sutrs</literal>.
4046 The <literal>fun</literal> member contains a pointer to the
4047 function which encodes/decodes the given type. Again, for the SUTRS
4048 record syntax, the value of <literal>fun</literal> would be
4049 <literal>z_SUTRS</literal> (a function pointer).
4052 If you receive an EXTERNAL which contains an octet-string value that
4053 you suspect of being an ASN.1-structured data value, you can use
4054 <literal>z_ext_gettypebyref</literal> to look for the provided
4056 If the return value is different from NULL, you can use the provided
4057 function to decode the BER string (see <xref linkend="odr.use"/>
4061 If you want to <emphasis>send</emphasis> EXTERNALs containing
4062 ASN.1-structured values in the occtet-aligned branch of the CHOICE, this
4063 is possible too. However, on the encoding phase, it requires a somewhat
4064 involved juggling around of the various buffers involved.
4067 If you need to add new, externally defined data types, you must update
4068 the struct above, in the source file <filename>prt-ext.h</filename>, as
4069 well as the encoder/decoder in the file <filename>prt-ext.c</filename>.
4070 When changing the latter, remember to update both the
4071 <literal>arm</literal> arrary and the list
4072 <literal>type_table</literal>, which drives the CHOICE biasing that
4073 is necessary to tell the different, structured types apart
4078 Eventually, the EXTERNAL processing will most likely
4079 automatically insert the correct OIDs or indirect-refs. First,
4080 however, we need to determine how application-context management
4081 (specifically the presentation-context-list) should fit into the
4086 <sect1 id="asn.pdu">
4087 <title>PDU Contents Table</title>
4089 We include, for reference, a listing of the fields of each top-level
4090 PDU, as well as their default settings.
4092 <table frame="top" id="asn.default.initialize.request">
4093 <title>Default settings for PDU Initialize Request</title>