-## $Id: Makefile.am,v 1.15 2001-10-23 21:00:19 adam Exp $
+## $Id: Makefile.am,v 1.16 2001-10-24 09:27:59 adam Exp $
docdir=$(pkgdatadir)/doc
-doc_DATA = $(srcdir)/yaz.sgml $(srcdir)/profiles.sgml \
- yaz.txt yaz.ps profiles.txt profiles.ps yaz.html \
- yaz-1.html yaz-2.html yaz-3.html yaz-4.html yaz-5.html \
- yaz-6.html yaz-7.html yaz-8.html yaz-9.html
-
-EXTRA_DIST = $(srcdir)/yaz.sgml $(srcdir)/profiles.sgml \
- yaz.txt yaz.ps profiles.txt profiles.ps yaz.html \
- yaz-1.html yaz-2.html yaz-3.html yaz-4.html yaz-5.html \
- yaz-6.html yaz-7.html yaz-8.html yaz-9.html
-
-yaz.txt: $(srcdir)/yaz.sgml
- sgml2txt -f $(srcdir)/yaz.sgml
-
-yaz.dvi: $(srcdir)/yaz.sgml
- sgml2latex -p a4 -o dvi $(srcdir)/yaz.sgml
-
-yaz.ps: $(srcdir)/yaz.sgml
- sgml2latex -p a4 -o ps $(srcdir)/yaz.sgml
-
-profiles.txt: $(srcdir)/profiles.sgml
- sgml2txt -f $(srcdir)/profiles.sgml
-
-profiles.dvi: $(srcdir)/profiles.sgml
- sgml2latex -p a4 -o dvi $(srcdir)/profiles.sgml
-
-profiles.ps: $(srcdir)/profiles.sgml
- sgml2latex -p a4 -o ps $(srcdir)/profiles.sgml
-
-yaz.html: $(srcdir)/yaz.sgml
- sgml2html $(srcdir)/yaz.sgml
-
XMLFILES=$(srcdir)/yaz.xml $(srcdir)/introduction.xml \
$(srcdir)/installation.xml $(srcdir)/indexdata.xml $(srcdir)/asn.xml \
$(srcdir)/tools.xml $(srcdir)/odr.xml $(srcdir)/comstack.xml \
$(srcdir)/frontend.xml $(srcdir)/license.xml $(srcdir)/future.xml \
$(srcdir)/client.xml $(srcdir)/zoom.xml
-$(srcdir)/book1.html: $(XMLFILES) $(srcdir)/yazhtml.dsl
+HTMLFILES = asn.external.html asn.html asn.oid.html asn.pdu.html \
+ asn.preparing.html client.commands.html client.html client.invoking.html \
+ client.searching.html comstack.addresses.html comstack.client.html \
+ comstack.common.html comstack.diagnostics.html comstack.html \
+ comstack.introduction.html comstack.server.html comstack.summary.html \
+ future.html indexdata.html installation.html installation.win32.html \
+ introduction.html license.html license.other.html odr.debugging.html \
+ odr.html odr.programming.html odr.use.html server.backend.html \
+ server.backendfunctions.html server.frontend.html server.html \
+ server.invocation.html server.main.html tools.html tools.nmem.html \
+ tools.oid.html yaz.html zoom.events.html zoom.html zoom.options.html \
+ zoom.records.html zoom.resultsets.html zoom.search.html
+
+DOCFILES=$(XMLFILES) $(HTMLFILES) yaz.pdf
+
+EXTRA_DIST = $(DOCFILES)
+
+doc_DATA = $(DOCFILES)
+
+$(srcdir)/yaz.html: $(XMLFILES) $(srcdir)/yazhtml.dsl
cd $(srcdir); jade -E14 -d yazhtml.dsl -t sgml xml.dcl yaz.xml
$(srcdir)/book1.php: $(XMLFILES) $(srcdir)/yazphp.dsl
-<!-- $Id: asn.xml,v 1.8 2001-08-23 09:12:09 adam Exp $ -->
- <chapter><title>The ASN Module</title>
- <sect1><title>Introduction</title>
+<!-- $Id: asn.xml,v 1.9 2001-10-24 09:27:59 adam Exp $ -->
+ <chapter id="asn"><title>The ASN Module</title>
+ <sect1 id="asn.introduction"><title>Introduction</title>
<para>
The &asn; module provides you with a set of C struct definitions for the
various PDUs of the protocol, as well as for the complex types
provides auxiliary definitions.
</para>
</sect1>
- <sect1><title>Preparing PDUs</title>
+ <sect1 id="asn.preparing"><title>Preparing PDUs</title>
<para>
A structure representing a complex ASN.1 type doesn't in itself contain the
</para>
</sect1>
- <sect1><title id="oid">Object Identifiers</title>
+ <sect1 id="asn.oid"><title id="oid">Object Identifiers</title>
<para>
When you refer to object identifiers in your application, you need to
be aware that SR and Z39.50 use two different set of OIDs to refer to
</note>
</sect1>
- <sect1><title>EXTERNAL Data</title>
+ <sect1 id="asn.external"><title>EXTERNAL Data</title>
<para>
In order to achieve extensibility and adaptability to different
</note>
</sect1>
- <sect1><title>PDU Contents Table</title>
+ <sect1 id="asn.pdu"><title>PDU Contents Table</title>
<para>
We include, for reference, a listing of the fields of each top-level
-<!-- $Id: client.xml,v 1.2 2001-08-13 09:42:54 adam Exp $ -->
- <chapter><title>The YAZ client</title>
- <sect1><title>Introduction</title>
+<!-- $Id: client.xml,v 1.3 2001-10-24 09:27:59 adam Exp $ -->
+ <chapter id="client"><title>The YAZ client</title>
+ <sect1 id="client.introduction"><title>Introduction</title>
<para>
yaz-client is a line-mode Z39.50 client. It supports a fair amount
of the functionality of the Z39.50-1995 standard, but some things you
Services (ItemOrder, ItemUpdate,..).
</para>
</sect1>
- <sect1><title>Invoking the YAZ client</title>
+ <sect1 id="client.invoking"><title>Invoking the YAZ client</title>
<para>
It can be started by typing
</para>
yaz-client -a - localhost
</screen>
</sect1>
- <sect1><title>YAZ client commands</title>
+ <sect1 id="client.commands"><title>YAZ client commands</title>
<para>
When the YAZ client has read options and connected to a target, if given,
it will display <literal>Z ></literal> and away your command.
</screen>
</listitem>
</varlistentry>
- <varlistentry><term>
+ <varlistentry id="sortspec"><term>
<literal>sort</literal> <replaceable>sortspecs</replaceable>
</term>
<listitem>
- <para>Sorts a result set. The sort command takes a sequence of
- sort specifications. A sort
+ <para>Sorts a result set. The sort command takes a
+ sequence of sort specifications. A sort
specification holds a field (sort criteria) and is followed by flags.
If the sort criteria includes <literal>=</literal> it is assumed
that the sort SortKey is of type sortAttributes using Bib-1.
</varlistentry>
</variablelist>
</sect1>
- <sect1><title>Searching</title>
+ <sect1 id="client.searching"><title>Searching</title>
<para>
The simplest example of a Prefix Query would be something like
<screen>
-<!-- $Id: comstack.xml,v 1.3 2001-08-13 09:42:54 adam Exp $ -->
- <chapter><title id="comstack">The COMSTACK Module</title>
+<!-- $Id: comstack.xml,v 1.4 2001-10-24 09:27:59 adam Exp $ -->
+ <chapter id="comstack"><title>The COMSTACK Module</title>
- <sect1><title>Synopsis (blocking mode)</title>
+ <sect1 id="comstack.synopsis"><title>Synopsis (blocking mode)</title>
<programlisting>
</programlisting>
</sect1>
- <sect1><title>Introduction</title>
+ <sect1 id="comstack.introduction"><title>Introduction</title>
<para>
The &comstack;
</para>
</sect1>
- <sect1><title>Common Functions</title>
+ <sect1 id="comstack.common"><title>Common Functions</title>
<sect2><title>Managing Endpoints</title>
</sect1>
- <sect1><title>Client Side</title>
+ <sect1 id="comstack.client"><title>Client Side</title>
<synopsis>
int cs_connect(COMSTACK handle, void *address);
</sect1>
- <sect1><title>Server Side</title>
+ <sect1 id="comstack.server"><title>Server Side</title>
<para>
To establish a server under the <application>inetd</application> server, you
</note>
</sect1>
- <sect1><title>Addresses</title>
+ <sect1 id="comstack.addresses"><title>Addresses</title>
<para>
The low-level format of the addresses are different depending on the
</sect1>
- <sect1><title>Diagnostics</title>
+ <sect1 id="comstack.diagnostics"><title>Diagnostics</title>
<para>
All functions return -1 if an error occurs. Typically, the functions
provided.
</para>
</sect1>
-
- <sect1><title>Enabling OSI Communication</title>
-
- <sect2><title>Installing Xtimosi</title>
- <para>
- Although you will have to down-load Peter Furniss' XTI/mOSI
- implementation for yourself, we've tried to make the integration as
- simple as possible.
- </para>
-
- <para>
- The latest version of xtimosi will generally be under
- </para>
-
- <screen>
- ftp://pluto.ulcc.ac.uk/ulcc/thinosi/xtimosi/
- </screen>
-
- <para>
- When you have down-loaded and unpacked the archive, it will (we assume)
- have created a directory called <literal>xtimosi</literal>.
- We suggest that you place this directory <emphasis>in the same
- directory</emphasis> where you unpacked the &yaz;
- distribution. This way, you shouldn't have to fiddle with the
- makefiles of &yaz; beyond uncommenting a few lines.
- </para>
-
- <para>
- Go to <literal>xtimosi/src</literal>, and type "make libmosi.a/".
- This should generally create the library, ready to use.
- </para>
-
- <note>
- <para>
- The currently available release of xtimosi has some inherent
- problems that make it disfunction on certain platforms - eg. the
- Digital OSF/1 workstations. It is supposedly primarily a
- compiler problem, and we hope to see a release that is generally
- portable. While we can't guarantee that it can be brought to work
- on your platform, we'll be happy to talk to you about problems
- that you might see, and relay information to the author of the
- software. There are some signs that the <application>gcc</application>
- compiler is more likely to produce a fully functional library, but this
- hasn't been verified (we think that the problem is limited to the use
- of hexadecimal escape-codes used in strings, which are silently
- ignored by some compilers).
- </para>
- <para>
- A problem has been encountered in the communication with
- ISODE-based applications. If the ISODE presentation-user calls
- <function>PReadRequest()</function> with a timeout value different
- from <literal>OK</literal> or <literal>NOTOK</literal>,
- he will get an immediate TIMEOUT abort when receiving large (>2041
- bytes, which is the SPDU-size that the ISODE likes to work with) packages
- from an xtimosi-based implementation (probably most
- other implementations as well, in fact). It seems to be a flaw in the
- ISODE API, and the workaround (for ISODE users) is to either not
- use an explicit timeout (switching to either blocking or
- nonblocking mode), or to check that the timer really has expired
- before closing the connection.
- </para>
- </note>
-
- <para>
- The next step in the installation is to modify the makefile in the toplevel
- &yaz;
- directory. The place to change is in the top of the file, and is
- clearly marked with a comment.
- </para>
-
- <para>
- Now run <literal>make</literal> in the &yaz; toplevel directory (do a
- <literal>make clean</literal> first, if the system has been previously
- made without OSI support). Use the &yaz;
- <application>yaz-ztest</application> and <application>yaz-client</application>
- demo programs to verify that OSI communication works OK. Then, you can go
- ahead and try to talk to other implementations.
- </para>
-
- <note>
- <para>
- Our interoperability experience is limited to version
- 7 of the Nordic SR-Nett package, which has had several
- protocol errors fixed from the earlier releases. If you have
- problems or successes in interoperating with other
- implementations, we'd be glad to hear about it, or to help
- you make things work, as our resources allow.
- </para>
- </note>
-
- <para>
- If you write your own applications based on &yaz;, and you wish to
- include OSI support, the procedure is equally simple. You should
- include the <filename>xmosi.h</filename> header file in addition to
- <filename>comstack.h</filename>. <filename>xmosi.h</filename>
- will define the manifest constant <literal>mosi_type</literal>, which you
- should pass to the <function>cs_create()</function> function. In
- addition, you should use the function <function>mosi_strtoaddr()</function>
- rather than <function>tcpip_strtoaddr()</function> when you need to
- prepare an address.
- </para>
-
- <para>
- When you link your application, you should include (after the
- <filename>libyaz.a</filename> library) the <literal>libmosi.a</literal>
- library, and the <filename>librfc.a</filename> library provided with
- &yaz; (for OSI transport).
- </para>
- <para>
- As always, it can be very useful, if not essential, to have a look at the
- example applications to see how things are done.
- </para>
-
- </sect2>
- <sect2><title>OSI Transport</title>
-
- <para>
- Xtimosi requires an implementation of the OSI transport service under
- the X/OPEN XTI API. We provide an implementation of the RFC1006
- encapsulation of OSI/TP0 in TCP/IP (through the Berkeley Sockets API),
- as an independent part of &yaz; (it's found under the
- <filename>rfc1006</filename> directory).
- If you have access to an OSI transport provider under XTI,
- you should be able to make that work too, although it may require
- tinkering with the <function>mosi_strtoaddr()</function> function.
- </para>
- </sect2>
-
- <sect2><title>Presentation Context Management</title>
-
- <para>
- To simplify the implementation, we use Peter Furniss' alternative (PRF)
- option format
- for the Control of the presentation negotiation phase. This format
- is enabled by default when you
- compile xtimosi.
- </para>
-
- <para>
- The current version of &yaz; does <emphasis>not</emphasis> support
- presentation-layer negotiation of response record formats. The primary
- reason is that we have had access to no other SR or Z39.50
- implementations over OSI that used this
- method. Secondarily, we believe that the EXPLAIN facility is a superior
- mechanism for relaying target capabilities in this respect. This is not to
- say that we have no intentions of supporting presentation context
- negotiation - we have just hitherto given it a lower priority than other
- aspects of the protocol.
- </para>
- <para>
- One thing is certain: The addition of this capability to &yaz; should
- have only a minimal impact on existing applications, and on the
- interface to the software in general. Most likely, we will add an extra
- layer of interface to the processing of EXPLAIN records, which will
- convert back and forth between <literal>oident</literal> records (see
- section <link linkend="oid">Object Identifiers</link>) and direct or
- indirect references, given the current association setup. Implementations
- based on any of the higher-level interfaces will most likely not have to
- be changed at all.
- </para>
- </sect2>
- </sect1>
- <sect1><title>Summary and Synopsis</title>
+ <sect1 id="comstack.summary"><title>Summary and Synopsis</title>
<synopsis>
#include <comstack.h>
-<!-- $Id: frontend.xml,v 1.5 2001-08-13 09:42:54 adam Exp $ -->
- <chapter><title id="server">Making an IR Server for Your Database</title>
+<!-- $Id: frontend.xml,v 1.6 2001-10-24 09:27:59 adam Exp $ -->
+ <chapter id="server"><title>Making an IR Server for Your Database</title>
<sect1><title>Introduction</title>
<para>
</note>
</sect1>
- <sect1><title>The Database Frontend</title>
+ <sect1 id="server.frontend"><title>The Database Frontend</title>
<para>
We refer to this software as a generic database frontend. Your
</para>
</sect1>
- <sect1><title>The Backend API</title>
+ <sect1 id="server.backend"><title>The Backend API</title>
<para>
The headers files that you need to use the interface are in the
</para>
</sect1>
- <sect1><title>Your main() Routine</title>
+ <sect1 id="server.main"><title>Your main() Routine</title>
<para>
As mentioned, your <function>main()</function> routine can be quite brief.
</note>
</sect1>
- <sect1><title>The Backend Functions</title>
+ <sect1 id="server.backendfunctions"><title>The Backend Functions</title>
<para>
For each service of the protocol, the backend interface declares one or
</sect2>
</sect1>
- <sect1><title>Application Invocation</title>
+ <sect1 id="server.invocation"><title>Application Invocation</title>
<para>
The finished application has the following
-<!-- $Id: future.xml,v 1.3 2001-08-13 09:42:54 adam Exp $ -->
- <chapter><title>Future Directions</title>
+<!-- $Id: future.xml,v 1.4 2001-10-24 09:27:59 adam Exp $ -->
+ <chapter id="future"><title>Future Directions</title>
<para>
We have a new and better version of the front-end server on the drawing
-<!-- $Id: indexdata.xml,v 1.4 2001-08-13 09:42:54 adam Exp $ -->
- <appendix><title>About Index Data</title>
+<!-- $Id: indexdata.xml,v 1.5 2001-10-24 09:27:59 adam Exp $ -->
+ <appendix id="indexdata"><title>About Index Data</title>
<para>
Index Data is a consulting and software-development enterprise that
-<!-- $Id: installation.xml,v 1.2 2001-07-19 23:29:40 adam Exp $ -->
- <chapter><title>Compilation and Installation</title>
+<!-- $Id: installation.xml,v 1.3 2001-10-24 09:27:59 adam Exp $ -->
+ <chapter id="installation"><title>Compilation and Installation</title>
<para>
The latest version of the software will generally be found at
</ulink>, or the address given at the top of this document.
</para>
- <sect1><title>UNIX</title>
+ <sect1 id="installation.unix"><title>UNIX</title>
<para>
Note that if your system doesn't have a native ANSI C compiler, you may
</para>
</sect1>
- <sect1><title>WIN32</title>
+ <sect1 id="installation.win32"><title>WIN32</title>
<para>
&yaz; is shipped with "makefiles" for the NMAKE tool that comes
sgml-namecase-general:t
End:
-->
-
\ No newline at end of file
+
-<!-- $Id: introduction.xml,v 1.3 2001-08-13 09:42:54 adam Exp $ -->
- <chapter><title>Introduction</title>
+<!-- $Id: introduction.xml,v 1.4 2001-10-24 09:27:59 adam Exp $ -->
+ <chapter id="introduction"><title>Introduction</title>
<para>
The &yaz; toolkit offers several different levels of access to the
-<!-- $Id: license.xml,v 1.3 2001-07-19 23:29:40 adam Exp $ -->
- <appendix><title>License</title>
+<!-- $Id: license.xml,v 1.4 2001-10-24 09:27:59 adam Exp $ -->
+ <appendix id="license"><title>License</title>
- <sect1><title>Index Data Copyright</title>
+ <sect1 id="license.indexdata"><title>Index Data Copyright</title>
<para>
Copyright © 1995-2001 Index Data.
</para>
<para>
- Permission to use, copy, modify, distribute, and sell this software and
- its documentation, in whole or in part, for any purpose, is hereby granted,
- provided that:
+ Permission to use, copy, modify, distribute, and sell this
+ software and its documentation, in whole or in part, for any
+ purpose, is hereby granted, provided that:
</para>
<para>
OF THIS SOFTWARE.
</para>
</sect1>
- <sect1><title>Additional Copyright Statements</title>
+ <sect1 id="license.other"><title>Additional Copyright Statements</title>
<para>
The optional CCL query language interpreter is covered by the following
-<!-- $Id: odr.xml,v 1.4 2001-08-13 09:42:54 adam Exp $ -->
- <chapter><title id="odr">The ODR Module</title>
+<!-- $Id: odr.xml,v 1.5 2001-10-24 09:27:59 adam Exp $ -->
+ <chapter id="odr"><title>The ODR Module</title>
- <sect1><title>Introduction</title>
+ <sect1 id="odr.introduction"><title>Introduction</title>
<para>
&odr; is the BER-encoding/decoding subsystem of &yaz;. Care as been taken
</para>
</sect1>
- <sect1><title id="odr-use">Using ODR</title>
+ <sect1 id="odr.use"><title id="odr-use">Using ODR</title>
<sect2><title>ODR Streams</title>
</sect2>
</sect1>
- <sect1><title id="odr-prog">Programming with ODR</title>
+ <sect1 id="odr.programming"><title id="odr-prog">Programming with ODR</title>
<para>
The API of &odr; is designed to reflect the structure of ASN.1, rather
</sect2>
</sect1>
- <sect1><title>Debugging</title>
+ <sect1 id="odr.debugging"><title>Debugging</title>
<para>
The protocol modules are suffering somewhat from a lack of diagnostic
-<!-- $Id: tools.xml,v 1.5 2001-08-13 09:42:54 adam Exp $ -->
- <chapter><title>Supporting Tools</title>
+<!-- $Id: tools.xml,v 1.6 2001-10-24 09:27:59 adam Exp $ -->
+ <chapter id="tools"><title>Supporting Tools</title>
<para>
In support of the service API - primarily the ASN module, which
a collection of tools that support the development of applications.
</para>
- <sect1><title>Query Syntax Parsers</title>
+ <sect1 id="tools.query"><title>Query Syntax Parsers</title>
<para>
Since the type-1 (RPN) query structure has no direct, useful string
</sect3>
</sect2>
</sect1>
- <sect1><title>Object Identifiers</title>
+ <sect1 id="tools.oid"><title>Object Identifiers</title>
<para>
The basic YAZ representation of an OID is an array of integers,
</sect1>
- <sect1><title>Nibble Memory</title>
+ <sect1 id="tools.nmem"><title>Nibble Memory</title>
<para>
Sometimes when you need to allocate and construct a large,
<!ENTITY comstack "<acronym>COMSTACK</acronym>">
<!ENTITY zoom "<acronym>ZOOM</acronym>">
]>
-<!-- $Id: yaz.xml,v 1.7 2001-10-23 21:00:19 adam Exp $ -->
-<book>
+<!-- $Id: yaz.xml,v 1.8 2001-10-24 09:27:59 adam Exp $ -->
+<book id="yaz">
<bookinfo>
<title>YAZ User's Guide and Reference</title>
<author><firstname>Sebastian</firstname><surname>Hammer</surname></author>
CDATA DSSSL>
]>
<!--
- $Id: yazhtml.dsl,v 1.5 2001-10-22 13:57:24 adam Exp $
+ $Id: yazhtml.dsl,v 1.6 2001-10-24 09:27:59 adam Exp $
-->
<style-sheet>
<style-specification use="docbook">
<style-specification-body>
+(define %use-id-as-filename% #t)
+(define %output-dir% "html")
(define %html-ext% ".html")
(define %shade-verbatim% #t)
CDATA DSSSL>
]>
<!--
- $Id: yazphp.dsl,v 1.4 2001-10-22 13:57:24 adam Exp $
+ $Id: yazphp.dsl,v 1.5 2001-10-24 09:27:59 adam Exp $
-->
<style-sheet>
<style-specification use="docbook">
<style-specification-body>
+(define %use-id-as-filename% #t)
+(define %output-dir% "php")
(define %html-ext% ".php")
(define %shade-verbatim% #t)
-<!-- $Id: zoom.xml,v 1.1 2001-10-23 21:00:19 adam Exp $ -->
- <chapter><title>ZOOM</title>
+<!-- $Id: zoom.xml,v 1.2 2001-10-24 09:27:59 adam Exp $ -->
+ <chapter id="zoom"><title>ZOOM</title>
<para>
&zoom; is an acronym for Z39.50 Object Oriented Model and is
that because of typedefs. All destroy methods should gracefully ignore a
<literal>NULL</literal> pointer.
</para>
- <sect1><title>Connections</title>
+ <sect1 id="zoom.connections"><title>Connections</title>
- <para>The connection object Z3950_connection describes
- the connection between your client and a server.
+ <para>The Connection object is a session with a target.
</para>
<synopsis>
#include <yaz/zoom.h>
const char *Z3950_connection_option (Z3950_connection c,
const char *key,
const char *val);
+ const char *Z3950_connection_host (Z3950_connection c);
</synopsis>
<para>
The <function>Z3950_connection_option</function> allows you to
the option is unchanged.
The function returns the previous value of the option.
</para>
- <synopsis>
- const char *Z3950_connection_host (Z3950_connection c);
-
- </synopsis>
+ <table frame="top"><title>ZOOM Connection Options</title>
+ <tgroup cols="3">
+ <colspec colwidth="4*" colname="name"></colspec>
+ <colspec colwidth="7*" colname="description"></colspec>
+ <colspec colwidth="3*" colname="default"></colspec>
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ <entry>Default</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row><entry>
+ implementationName</entry><entry>Name of Your client
+ </entry><entry>none</entry></row>
+ <row><entry>
+ user</entry><entry>Authentication user name
+ </entry><entry>none</entry></row>
+ <row><entry>
+ group</entry><entry>Authentication group name
+ </entry><entry>none</entry></row>
+ <row><entry>
+ pass</entry><entry>Authentication password
+ </entry><entry>none</entry></row>
+ <row><entry>
+ proxy</entry><entry>Proxy host
+ </entry><entry>none</entry></row>
+ <row><entry>
+ async</entry><entry>If true (1) the connection operates in
+ asynchronous operatio which means that all calls are non-blocking
+ except <function>Z3950_event</function>.
+ </entry><entry>0</entry></row>
+ <row><entry>
+ maximumRecordSize</entry><entry> Maximum size of single record.
+ </entry><entry>1 MB</entry></row>
+ <row><entry>
+ preferredMessageSize</entry><entry> Maximum size of multiple records.
+ </entry><entry>1 MB</entry></row>
+ </tbody>
+ </tgroup>
+ </table>
<para>
Function <function>Z3950_connection_host</function> returns
- the host for the connection as specified in either a call to
+ the host for the connection as specified in a call to
<function>Z3950_connection_new</function> or
<function>Z3950_connection_connect</function>.
This function returns <literal>NULL</literal> if host isn't
non-<literal>NULL</literal>.
</para>
</sect1>
- <sect1><title>Search objects</title>
+ <sect1 id="zoom.search"><title>Search objects</title>
<para>
Search objects defines how result sets are obtained. They
act like queries.
<para>
Create search objects using <function>Z3950_search_create</function>
and destroy them by calling <function>Z3950_search_destroy</function>.
- RPN-queries can be specified in PQF notation by using the
+ RPN-queries can be specified in <link linkend="PQF">PQF</link>
+ notation by using the
function <function>Z3950_search_prefix</function>. More
- query types will be added later, such as CCL to RPN-mapping, CCL
- query, etc.
- In addition to a search a sort critieria may be set. Function
- <function>Z3950_search_sortby</function> specifies a sort
- criteria using the same string notation for sort as offered by
- the YAZ client.
+ query types will be added later, such as
+ <link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
+ etc. In addition to a search, a sort critieria may be set. Function
+ <function>Z3950_search_sortby</function> specifies a
+ sort criteria using the same string notation for sort as offered by
+ the <link linkend="sortspec">YAZ client</link>.
</para>
</sect1>
- <sect1><title>Result sets</title>
+ <sect1 id="zoom.resultsets"><title>Result sets</title>
<para>
- The result set describes a collection of records obtained from
+ The result set object is a container for records returned from
+ a target.
search.
</para>
<synopsis>
a result set given a connection - and search object.
Destroy a result set by calling
<function>Z3950_resultset_destroy</function>.
- Simple clients using YAZ' prefix query format may use
- function <function>Z3950_connection_search_pqf</function>
- instead.
+ Simple clients using PQF only may use function
+ <function>Z3950_connection_search_pqf</function> instead.
</para>
<synopsis>
const char *Z3950_resultset_option (Z3950_resultset r,
void *Z3950_resultset_get (Z3950_resultset s, int pos,
const char *type, int *len);
- void Z3950_resultset_records (Z3950_resultset r,
- Z3950_record *recs,
- size_t *cnt);
</synopsis>
<para>
- Description of result sets here.
+ Function <function>X3950_resultset_options</function> sets or
+ modifies an option for a result set similar to
+ <function>Z3950_connection_option</function>.
</para>
+ <para>
+ The number of hits also called result-set is returned by
+ function <function>3950_resultset_size</function>.
+ </para>
+ <para>
+ Function <function>Z3950_resultset_get</function> is similar to
+ <link linkend="zoom.record.get">
+ <function>Z3950_record_get</function></link> but
+ instead of operating on a record object it operates on a record on
+ a given offset within a result set.
+ </para>
+ <table frame="top"><title>ZOOM Result set Options</title>
+ <tgroup cols="3">
+ <colspec colwidth="4*" colname="name"></colspec>
+ <colspec colwidth="7*" colname="description"></colspec>
+ <colspec colwidth="2*" colname="default"></colspec>
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ <entry>Default</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row><entry>
+ piggyback</entry><entry>True (1) if piggyback should be
+ used in searches; false (0) if not.
+ </entry><entry>1</entry></row>
+ <row><entry>
+ start</entry><entry>Offset of first record we wish to
+ retrieve from the target. Note first record has offset 0
+ unlike the protocol specifications where first record has position
+ 1.
+ </entry><entry>0</entry></row>
+ <row><entry>
+ count</entry><entry>Number of records to be retrieved.
+ </entry><entry>0</entry></row>
+ <row><entry>
+ elementSetName</entry><entry>Element-Set name of records.
+ Most targets should honor element set name <literal>B</literal>
+ and <literal>F</literal> for brief and full respectively.
+ </entry><entry>none</entry></row>
+ <row><entry>
+ preferredRecordSyntax</entry><entry>Preferred Syntax, like
+ <literal>USMARC</literal>, <literal>SUTRS</literal>, etc.
+ </entry><entry>none</entry></row>
+ <row><entry>
+ databaseName</entry><entry>One or more database names
+ separated by character plus (<literal>+</literal>).
+ </entry><entry>Default</entry></row>
+ </tbody>
+ </tgroup>
+ </table>
</sect1>
- <sect1><title>Records</title>
+ <sect1 id="zoom.records"><title>Records</title>
<para>
A record object is a retrival record on the client side -
created from result sets.
</para>
<synopsis>
+ void Z3950_resultset_records (Z3950_resultset r,
+ Z3950_record *recs,
+ size_t *cnt);
Z3950_record Z3950_resultset_record (Z3950_resultset s, int pos);
- Z3950_record Z3950_resultset_record_immediate (Z3950_resultset s,
- int pos);
-
void *Z3950_record_get (Z3950_record rec, const char *type,
int *len);
void Z3950_record_destroy (Z3950_record rec);
</synopsis>
+ <para>
+ Records are created by functions
+ <function>Z3950_resultset_records</function> or
+ <function>Z3950_resultset_record</function>
+ and destroyed by <function>Z3950_resultset_destroy</function>.
+ </para>
+ <para>
+ A single record is created and returned by function
+ <function>Z3950_resultset_record</function> that takes a
+ position as argument. First record has position zero.
+ If no record could be obtained <literal>NULL</literal>.
+ </para>
+ <para>
+ Function <function>Z39_resultset_records</function>retrieves
+ a number of records from a result set. Options <literal>start</literal>
+ and <literal>count</literal> specifies the range of records to
+ be returned. Upon completion <literal>recs[0], ..recs[*cnt]</literal>
+ holds record objects for the records. These array of records
+ <literal>recs</literal> should be allocate prior to calling
+ <function>Z3950_resultset_records</function>. Note that for
+ records that couldn't be retrieved from the target
+ <literal>recs[ ..]</literal> is <literal>NULL</literal>.
+ </para>
+ <para id="zoom.record.get">
+ In order to extract information about a single record,
+ <function>Z3950_record_get</function> is provided. The
+ function returns a pointer to certain record information. The
+ nature (type) of the pointer depends on the <function>type</function>
+ given. In addition for certain types, the length
+ <literal>len</literal> passed will be set to the size in bytes of
+ the returned information. The types <literal>database</literal>,
+ <literal>syntax</literal> and <literal>render</literal> are
+ supported. More will be added later.
+ </para>
</sect1>
- <sect1><title>Options</title>
+ <sect1 id="zoom.options"><title>Options</title>
<para>
Most objects in &zoom; allows you to specify options to change
behaviour. From an implementation point of view a set of options
void *handle);
</synopsis>
</sect1>
- <sect1><title>Events</title>
+ <sect1 id="zoom.events"><title>Events</title>
<para>
If you're developing non-blocking applications you have to deal
with events.
<synopsis>
int Z3950_event (int no, Z3950_connection *cs);
</synopsis>
+ <para>
+ The <function>Z3950_event</function> executes pending events for
+ a number of connections. Supply the number of connections in
+ <literal>no</literal> and an array of connections in
+ <literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
+ A pending event could be a sending a search, receiving a response,
+ etc.
+ When an event has a occured for one of the connections this function
+ returns a positive integer <literal>n</literal> denoting that an event
+ occurred for connection <literal>cs[n-1]</literal>.
+ When no events are pending for the connections a value of zero is
+ returned.
+ To make sure all outstanding requests are performed call is function
+ repeatedly until zero is returned.
+ </para>
</sect1>
</chapter>
projects / yaz-moved-to-github.git / commitdiff