<listitem>
<para>
Supports
- <ulink url="&url.solr;">Solr</ulink> Web Service version 1.4.x
+ <ulink url="&url.solr;">Apache Solr</ulink> Web Service version 1.4.x
(client side only)
</para>
</listitem>
<title>Reading this Manual</title>
<para>
Most implementors only need to read a fraction of the
- material in thie manual, so a quick walkthrough of the chapters
+ material in this manual, so a quick walkthrough of the chapters
is in order.
</para>
<itemizedlist>
<listitem>
<para>
<xref linkend="installation"/> contains installation
- instructions for &yaz;. You don't need reading this
+ instructions for &yaz;. You don't need to read this
if you expect to download &yaz; binaries.
However, the chapter contains information about how
to make <emphasis>your</emphasis> application link
<listitem>
<para>
<xref linkend="zoom"/> describes the ZOOM API of &yaz;.
- This is definitely worth a read if you wish to develop a Z39.50/SRU
+ This is definitely worth reading if you wish to develop a Z39.50/SRU
client.
</para>
</listitem>
<listitem>
<para>
<xref linkend="yaz-client"/> describes how to use the &yaz; Z39.50
- client. If you're developer and wish to test your server
+ client. If you're a developer and wish to test your server
or a server from another party, you might find this chapter
useful.
</para>
<xref linkend="odr"/> goes through the details of the
ODR module which is the work horse that encodes and decodes
BER packages. Implementors using ZOOM only, do <emphasis>not</emphasis>
- need reading this.
+ need to read this.
Most other Z39.50 implementors only need to read the first two
sections (<xref linkend="odr.introduction"/> and
<xref linkend="odr.use"/>).
level APIs of &yaz;.
</para>
<para>
- The YAZ toolkit modules is shown in figure <xref linkend="yaz.layer"/>.
+ The YAZ toolkit modules are shown in figure <xref linkend="yaz.layer"/>.
</para>
<figure id="yaz.layer">
<title>YAZ layers</title>
<note>
<para>
If you are using the premade definitions of the &asn; module, and you
- are not adding new protocol of your own, the only parts of &odr; that you
+ are not adding a new protocol of your own, the only parts of &odr; that you
need to worry about are documented in
<xref linkend="odr.use"/>.
</para>
<ulink url="&url.automake;">Automake</ulink> and
<ulink url="&url.libtool;">Libtool</ulink>
are used to generate Makefiles and configure &yaz; for the system.
- You do <emphasis>not</emphasis> these tools unless you're using the
+ You do <emphasis>not</emphasis> need these tools unless you're using the
Git version of &yaz;.
</para>
<para>
&yaz; includes a tiny ASN.1 compiler. This compiler is
written in <ulink url="&url.tcl;">Tcl</ulink>.
But as for Bison you do not need it unless you're using Git
- version of &yaz; or you're using the compiler to built own codecs
+ version of &yaz; or you're using the compiler to build your own codecs
for private ASN.1.
</para>
<para>
<replaceable>prefix</replaceable>. By default configure will
search for iconv on the system. Use this option if it
doesn't find iconv. Alternatively,
- <literal>--without-iconv</literal>, can be uset to force &yaz;
+ <literal>--without-iconv</literal>, can be used to force &yaz;
not to use iconv.
</para>
</listitem>
<replaceable>prefix</replaceable>.
Use this option if you want XSLT and XML support.
By default, configure will
- search for libxslt on the system. Use this option if it
+ search for libxslt on the system. Use this option if
libxslt is not found automatically. Alternatively,
<literal>--without-xslt</literal>, can be used to force &yaz;
not to use libxslt.
<replaceable>prefix</replaceable>.
Use this option if you want &yaz; to use XML and support SRU/Solr.
By default, configure will
- search for libxml2 on the system. Use this option if it
+ search for libxml2 on the system. Use this option if
libxml2 is not found automatically. Alternatively,
<literal>--without-xml2</literal>, can be used to force &yaz;
not to use libxml2.
<varlistentry>
<term>
- <literal>--with-libgcrypt</literal>[=<replaceable>prefix</replaceable>]
- </term>
- <listitem>
- <para>&yaz; will be linked with
- <ulink url="&url.libgcrypt;">Libgcrypt</ulink> in the prefix if given.
- If prefix is not given, the libraries exposed by the script
- <application>libgcrypt-config</application> will be used if found.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
<literal>--with-memcached</literal>
</term>
<listitem>
<para>&yaz; will be linked with
<ulink url="&url.libmemcached;">libMemcached</ulink> to allow
for result-set caching for ZOOM.
- The prefix can not be given. Note that YAZ will only search
- for libMemcached if Libgcrypt is also enabled.
+ The prefix can not be given.
+ Note that 0.40 of libmemcached is required.
</para>
</listitem>
</varlistentry>
<para>&yaz; will be linked with the hiredis C library
to allow for result-set caching for ZOOM on a
<ulink url="&url.redis;">redis</ulink> server.
- The prefix can not be given. Note that YAZ will only search
- for hiredis if Libgcrypt is also enabled.
+ The prefix can not be given.
</para>
</listitem>
</varlistentry>
This section describes how to compile - and link your own
applications using the &yaz; toolkit.
If you're used to Makefiles this shouldn't be hard. As for
- other libraries you have used before, you have to set a proper include
+ other libraries you have used before, you need to set a proper include
path for your C/C++ compiler and specify the location of
&yaz; libraries. You can do it by hand, but generally we suggest
you use the <filename>yaz-config</filename> that is generated
</sect2>
</sect1>
<sect1 id="installation.win32">
- <title>WIN32</title>
+ <title>Windows</title>
<para>The easiest way to install YAZ on Windows is by downloading
an installer from
<ulink url="&url.yaz.download.win32;">here</ulink>.
</para>
<sect2 id="installation.win32.source">
- <title>Compiling from Source on WIN32</title>
+ <title>Compiling from Source on Windows</title>
<para>
&yaz; is shipped with "makefiles" for the NMAKE tool that comes
with <ulink url="&url.vstudio;">
Microsoft Visual Studio</ulink>. It has been tested with
- Microsoft Visual Studio 2003/2005/2008.
+ Microsoft Visual Studio 2015.
</para>
<para>
Start a command prompt and switch the sub directory
If <literal>HAVE_LIBXML2</literal> is set to 1, YAZ is compiled
with SRU support. In this configuration, set
<literal>LIBXML2_DIR</literal> to the
- <ulink url="&url.libxml2;">libxml2</ulink> source directory
- and
- <literal>ZLIB_DIR</literal> to the zlib directory.
- </para>
- <para>
- Windows versions of libxslt, libxml2, zlib and iconv can be found
- <ulink url="&url.libxml2.download.win32;">
- Igor Zlatković' site</ulink>.
- </para>
- <note>
- <para>
- YAZ is not using zlib but libxml2 is depending on it.
- </para>
- </note>
+ <ulink url="&url.libxml2;">libxml2</ulink> source directory.
+ </para>
+ <para>
+ You can get pre-compiled Libxml2+Libxslt DLLs and headers from
+ <ulink url="&url.libxml2.download.windows;">here</ulink>.
+ Should you with to compile those libraries yourself, refer to
+ to <xref linkend="installation.windows.libxml2"/>
+ </para>
</listitem>
</varlistentry>
<varlistentry>
</para>
<note>
<para>
- libxslt depends libxml2.
+ libxslt depends on libxml2.
</para>
</note>
</listitem>
<term><filename>bin/yaz-icu.exe</filename></term>
<listitem><para>This program exposes the ICU wrapper library if that
is enabled for YAZ. Only if ICU is available this program is
- build.
+ built.
</para></listitem>
</varlistentry>
<varlistentry>
<term><filename>bin/zoomtst1.exe</filename>,
<filename>bin/zoomtst2.exe</filename>, ..</term>
<listitem><para>
- Several small applications that demonstrates the ZOOM API.
+ Several small applications that demonstrate the ZOOM API.
</para></listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="installation-linking-yaz-win32">
- <title>How to make apps using YAZ on WIN32</title>
+ <title>How to make apps using YAZ on Windows</title>
<para>
- This section will go though the process of linking your WIN32
+ This section will go though the process of linking your Windows
applications with &yaz;.
</para>
<para>
Some people are confused by the fact that we use the nmake
tool to build &yaz;. They think they have to do that too - in order
- to make their WIN32 applications work with &yaz;. The good news is that
+ to make their Windows applications work with &yaz;. The good news is that
you don't have to. You can use the integrated environment of
Visual Studio if desired for your own application.
</para>
</variablelist>
</para>
</sect2>
+
+ <sect2 id="installation.windows.libxml2">
+ <title>Compiling Libxml2 and Libxslt on windows</title>
+ <para>
+ Download libxml2 and Libxslt source and unpack it.
+ In the example below we install Libxml2 2.9.2 and Libxslt 1.1.28
+ for 32-bit, so we use the destination directories
+ libxml2.2.9.2.win32 and libxslt-1.1.28.win32 to reflect both
+ version and architecture.
+ <screen>
+ cd win32
+ cscript configure.js prefix=c:\libxml2-2.9.2.win32 iconv=no
+ nmake
+ nmake install
+ </screen>
+ </para>
+ <note>
+ <para>
+ There's an error in <filename>configure.js</filename> for Libxml2 2.9.2.
+ Line 17 should be assigned to <filename>configure.ac</filename>
+ rather than <filename>configure.in</filename>.
+ </para>
+ </note>
+ <para>
+ For Libxslt it is similar. We must ensure that compilation of
+ Libxslt links against the already installed libxml2.
+ <screen>
+ cd win32
+ cscript configure.js prefix=c:\libxslt-1.1.28.win32 iconv=no \
+ lib=c:\libxml2-2.9.2.win32\lib \
+ include=c:\libxml2-2.9.2.win32\include\libxml2
+ nmake
+ nmake install
+ </screen>
+ </para>
+ </sect2>
+
</sect1>
</chapter>
<!--
and more apparent over time. So when the first &zoom; specification
became available,
an implementation for &yaz; was quickly developed. For the first time, it is
- now as easy (or easier!) to develop clients than servers with &yaz;. This
+ now as easy (or easier!) to develop clients as it is to develop
+ servers with &yaz;. This
chapter describes the &zoom; C binding. Before going further, please
reconsider whether C is the right programming language for the job.
There are other language bindings available for &yaz;, and still
The C language misses features found in object oriented languages
such as C++, Java, etc. For example, you'll have to manually,
destroy all objects you create, even though you may think of them as
- temporary. Most objects has a <literal>_create</literal> - and a
+ temporary. Most objects have a <literal>_create</literal> - and a
<literal>_destroy</literal> variant.
All objects are in fact pointers to internal stuff, but you don't see
that because of typedefs. All destroy methods should gracefully ignore a
You can prefix the host with a scheme followed by colon. The
default scheme is <literal>tcp</literal> (Z39.50 protocol).
The scheme <literal>http</literal> selects SRU/get over HTTP by default,
- but can overridded to use SRU/post, SRW and the Solr protocol.
+ but can overridden to use SRU/post, SRW, and the Solr protocol.
</para>
<para>
You can prefix the scheme-qualified host-string with one or more
clientIP</entry><entry>Client IP. If set, is
encoded in the otherInfo area of a Z39.50 PDU with OID
1.2.840.10003.10.1000.81.3. Holds the original IP addreses
- of a client. Is used of ZOOM is used in a gateway of some sort.
+ of a client. Is used if ZOOM is used in a gateway of some sort.
</entry><entry>none</entry></row>
<row><entry>
async</entry><entry>If true (1) the connection operates in
</entry><entry>none</entry></row>
<row><entry>
databaseName</entry><entry>One or more database names
- separated by character plus (<literal>+</literal>), which to
+ separated by character plus (<literal>+</literal>), which is to
be used by subsequent search requests on this Connection.
</entry><entry>Default</entry></row>
<row><entry>
</entry><entry>1</entry></row>
<row><entry>
mediumSetPresentNumber</entry><entry>This value represents
- the number of records to be returned as part of a search when when
+ the number of records to be returned as part of a search when
hits is less than or equal to large set lower bound and if hits
is greater than small set upper bound.
</entry><entry>0</entry></row>
</entry><entry>none</entry></row>
<row><entry>
mediumSetElementSetName</entry><entry>
- The element set name to be for medium-sized result sets.
+ The element set name to be used for medium-sized result sets.
</entry><entry>none</entry></row>
<row><entry>
init_opt_search, init_opt_present, init_opt_delSet, etc.</entry><entry>
<row><entry>
sru_version</entry><entry>
SRU/SRW version. Should be <literal>1.1</literal>, or
- <literal>1.2</literal>. This is , prior to connect, the version
+ <literal>1.2</literal>. This is, prior to connect, the version
to offer (highest version). And following connect (in fact
first operation), holds the negotiated version with the server
(same or lower version).
</entry><entry>1.2</entry></row>
+ <row id="zoom.extraArgs.option"><entry>
+ extraArgs</entry><entry>
+ Extra arguments for SRU/Solr URLs. The value must be
+ URL encoded already.
+ </entry><entry></entry></row>
<row id="zoom.facets.option"><entry>
facets</entry><entry>
- Requested or recommend facets may be given before a search is sent.
+ Requested or recommended facets may be given before a search is sent.
The value of this setting is described in <xref linkend="facets"/>
For inspection of the facets returned, refer to the functions
described in <xref linkend="zoom.facets"/>.
If given and non-empty,
<ulink url="&url.libmemcached;">libMemcached</ulink>
will be configured for the connection.
- This option is inspected by ZOOM when a connection is established.
+ This option is inspected by ZOOM when a connection is established.
If the <literal>memcached</literal> option is given
and YAZ is compiled without libMemcached support, an internal
diagnostic (10018) will be thrown.
libMemcached support is available for YAZ 5.0.13 or later. If this
option is supplied for an earlier version of YAZ, it is
<emphasis>ignored</emphasis>.
- The value of this option is a string passed verbatim to
- the <function>memcached</function> function part of libMemcached.
- Refer to man page
- <ulink url="http://manned.org/memcached.3">memcached(3)</ulink>.
- Earlier versions of libMemcached
- do not offer this function. In this case only the option
- <literal>--server=</literal><replaceable>host</replaceable> may
- be given (YAZ emulates that part of libMemcached).
+ The value of this option is a list options - each is of the
+ form <literal>--name=value</literal>.
+ Option <literal>--server=</literal>host[:port] specifies a memcached
+ server. It may be repeated for multiple memcached servers.
+ Option <literal>--expire=</literal>seconds sets expiry time in seconds
+ for how long result sets are to be cached.
</entry><entry>none</entry></row>
<row><entry>
redis</entry><entry>
redis support is available for YAZ 5.2.0 or later. If this
option is supplied for an earlier version of YAZ, it is
<emphasis>ignored</emphasis>.
- The value of this option is a set options, similar to that
- of the memcached function. At this stage only --server=host[:port]
- is supported. Later versions of YAZ might honor expiry for various
- items and other things that tune the redis usage.
+ The value of this option is a set of options, similar to that
+ of the memcached setting. At this stage only --server=host[:port]
+ and --expire=seconds are supported.
</entry><entry>none</entry></row>
</tbody>
</tgroup>
The calls <function>ZOOM_connection_new</function> and
<function>ZOOM_connection_connect</function> establishes a TCP/IP
connection and sends an Initialize Request to the target if
- possible. In addition, the calls waits for an Initialize Response
+ possible. In addition, the calls wait for an Initialize Response
from the target and the result is inspected (OK or rejected).
</para>
<para>
<sect2 id="zoom.sru.init.behavior">
<title>SRU/Solr Protocol behavior</title>
<para>
- The HTTP based protocols (SRU, SRW, Solr) doesn't feature an
+ The HTTP based protocols (SRU, SRW, Solr) do not feature an
Inititialize Request, so the connection phase merely establishes a
TCP/IP connection with the HTTP server.
</para>
<function>ZOOM_query_sortby2</function> is similar to
<function>ZOOM_query_sortby</function> but allows a strategy for
sorting. The reason for the strategy parameter is that some
- protocols offers multiple ways of performing sorting.
+ protocols offer multiple ways of performing sorting.
For example, Z39.50 has the standard sort, which is performed after
search on an existing result set.
It's also possible to use CQL in Z39.50 as the query type and use
</synopsis>
<para>
Function <function>ZOOM_connection_search</function> creates
- a result set given a connection and query.
+ a result set, given a connection and query.
Destroy a result set by calling
<function>ZOOM_resultset_destroy</function>.
- Simple clients may using PQF only may use function
+ Simple clients using PQF only, may use the function
<function>ZOOM_connection_search_pqf</function> in which case
creating query objects is not necessary.
</para>
and <function>ZOOM_connection_option_set</function>.
</para>
<para>
- The number of hits also called result-count is returned by
+ The number of hits, also called result-count, is returned by
function <function>ZOOM_resultset_size</function>.
</para>
<table id="zoom.resultset.options"
<row>
<entry>searchresult.size</entry>
<entry>
- number of search result entries. This option is-nonexistant
+ number of search result entries. This option is non-existent
if no entries are returned by the server.
</entry>
</row>
<para>
<function>ZOOM_resultset_sort</function> and
<function>ZOOM_resultset_sort1</function> both sort an existing
- result-set. The sort_type parameter is not use. Set it to "yaz".
+ result-set. The sort_type parameter is not used. Set it to "yaz".
The sort_spec is same notation as ZOOM_query_sortby and identical
to that offered by yaz-client's
<link linkend="sortspec">sort command</link>.
The high-level mode allows you to fetch a range of records from
the result set with a given start offset. When you use this mode
the client will automatically use piggyback if that is possible
- with the target and perform one or more present requests as needed.
+ with the target, and perform one or more present requests as needed.
Even if the target returns fewer records as part of a present response
because of a record size limit, etc. the client will repeat sending
present requests. As an example, if option <literal>start</literal>
<para>
Current version of &yaz; does not take advantage of a result set id
returned by the SRU server. Future versions might do, however.
- Since, the ZOOM driver does not save result set IDs any
+ Since the ZOOM driver does not save result set IDs, any
present (retrieval) is transformed to a SRU SearchRetrieveRequest
with same query but, possibly, different offsets.
</para>
SRU SearchRetrieveRequest.
</para>
<para>
- Solr queries has to be done in Solr query format.
+ Solr queries need to be done in Solr query format.
</para>
<para>
- Unfortunately, SRU or Solr does not define a database setting. Hence,
+ Unfortunately, SRU and Solr do not define a database setting. Hence,
<literal>databaseName</literal> is unsupported and ignored.
However, the path part in host parameter for functions
<function>ZOOM_connecton_new</function> and
Function <function>ZOOM_resultset_records</function> retrieves
a number of records from a result set. Parameter <literal>start</literal>
and <literal>count</literal> specifies the range of records to
- be returned. Upon completion array
+ be returned. Upon completion, the array
<literal>recs[0], ..recs[count-1]</literal>
holds record objects for the records. The array of records
<literal>recs</literal> should be allocated prior the call
<function>ZOOM_resultset_records</function>. Note that for those
- records that couldn't be retrieved from the target
+ records that couldn't be retrieved from the target,
<literal>recs[ ..]</literal> is set to <literal>NULL</literal>.
</para>
<para id="zoom.record.get">
The <parameter>type</parameter> is a string of the format:
</para>
<para>
- <replaceable>format</replaceable>[;charset=<replaceable>from</replaceable>[/<replaceable>opacfrom</replaceable>][,<replaceable>to</replaceable>]][;format=<replaceable>v</replaceable>]
+ <replaceable>format</replaceable>[;charset=<replaceable>from</replaceable>[/<replaceable>opacfrom</replaceable>][,<replaceable>to</replaceable>]][;format=<replaceable>v</replaceable>][;base64=<replaceable>xpath</replaceable>]
</para>
<para>
- where <replaceable>format</replaceable> specifies the format of the
- returned record, <replaceable>from</replaceable>
+ If <literal>charset</literal> is given, then <replaceable>from</replaceable>
specifies the character set of the record in its original form
(as returned by the server), <replaceable>to</replaceable> specifies
- the output (returned)
- character set encoding.
- If <replaceable>to</replaceable> is omitted UTF-8 is assumed.
+ the output (returned) character set encoding.
+ If <replaceable>to</replaceable> is omitted, then UTF-8 is assumed.
If charset is not given, then no character set conversion takes place.
- </para>
-
- <para>OPAC records may be returned in a different
- set from the bibliographic MARC record. If this is this the case,
+ OPAC records may be returned in a different
+ set from the bibliographic MARC record. If this is this the case,
<replaceable>opacfrom</replaceable> should be set to the character set
of the OPAC record part.
</para>
+
+ <para>
+ The <literal>format</literal> is generic but can only be used to
+ specify XML indentation when the value <replaceable>v</replaceable>
+ is 1 (<literal>format=1</literal>).
+ </para>
+ <para>
+ The <literal>base64</literal> allows a full record to be extracted
+ from base64-encoded string in an XML document.
+ </para>
<note>
<para>
Specifying the OPAC record character set requires YAZ 4.1.5 or later.
</para>
+ <para>
+ Specifying the base64 parameter requires YAZ 4.2.35 or later.
+ </para>
</note>
<para>
The format argument controls whether record data should be XML
The following are the supported values for <replaceable>form</replaceable>.
<variablelist>
<varlistentry><term><literal>database</literal></term>
- <listitem><para>Database of record is returned
+ <listitem><para>The Database of the record is returned
as a C null-terminated string. Return type
<literal>const char *</literal>.
</para></listitem>
</varlistentry>
<varlistentry><term><literal>render</literal></term>
<listitem><para>The record is returned in a display friendly
- format. Upon completion buffer is returned
+ format. Upon completion, buffer is returned
(type <literal>const char *</literal>) and length is stored in
<literal>*len</literal>.
</para></listitem>
Present.
The functions may block (and perform network I/O) - even though option
<literal>async</literal> is 1, because they return records objects.
- (and there's no way to return records objects without retrieving them!).
+ (And there's no way to return records objects without retrieving them!)
</para>
<para>
There is a trick, however, in the usage of function
An array of facets field can be returned by
<function>ZOOM_resultset_facets</function>. The length of the array is
given by <function>ZOOM_resultset_facets_size</function>. The array is
- zero-based and last entry will be at
+ zero-based and the last entry will be at
<function>ZOOM_resultset_facets_size(result_set)</function>-1.
</para>
<para id="zoom.resultset.facets_names">
It is possible to interate over facets by name, by calling
<function>ZOOM_resultset_facets_names</function>.
- This will return an const array of char * where each string can be used
+ This will return a const array of char * where each string can be used
as parameter for <function>ZOOM_resultset_get_facet_field</function>.
</para>
<para>
<parameter>startpqf</parameter>.
If the operation was successful, the size of the scan set can be
retrieved by a call to <function>ZOOM_scanset_size</function>.
- Like result sets, the items are numbered 0,..size-1.
+ Like result sets, the items are numbered 0..size-1.
To obtain information about a particular scan term, call function
<function>ZOOM_scanset_term</function>. This function takes
a scan set offset <literal>pos</literal> and returns a pointer
<!-- all the ILL PDU options should go here too -->
</itemizedlist>
<para>
- To create an extended service operation a <literal>ZOOM_package</literal>
+ To create an extended service operation, a <literal>ZOOM_package</literal>
must be created. The operation is a five step operation. The
package is created, package is configured by means of options,
- the package is send, result is inspected (by means of options),
+ the package is sent, result is inspected (by means of options),
the package is destroyed.
</para>
<synopsis>
The <parameter>type</parameter> specifies the actual extended service
package type to be sent.
</para>
+ <table frame="top" id="zoom.extendedservices.type">
+ <title>Extended Service Type</title>
+ <tgroup cols="2">
+ <colspec colwidth="3*" colname="value"></colspec>
+ <colspec colwidth="7*" colname="description"></colspec>
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>itemorder</entry><entry>Item Order</entry>
+ </row>
+ <row>
+ <entry>update</entry><entry>Record Update</entry>
+ </row>
+ <row>
+ <entry>create</entry><entry>Database Create</entry>
+ </row>
+ <row>
+ <entry>drop</entry><entry>Database Drop</entry>
+ </row>
+ <row>
+ <entry>commit</entry><entry>Commit Operation</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
<table frame="top" id="zoom.extendedservices.options">
<title>Extended Service Common Options</title>
<tgroup cols="3">
<row>
<entry>package-name</entry>
<entry>Extended Service Request package name. Must be specified
- as part of a request</entry>
+ as part of a request.</entry>
<entry>none</entry>
</row>
<row>
<entry>user-id</entry>
- <entry>User ID of Extended Service Package. Is a request option</entry>
+ <entry>User ID of Extended Service Package. Is a request option.</entry>
<entry>none</entry>
</row>
<row>
<sect2 id="zoom.item.order">
<title>Item Order</title>
<para>
- For Item Order, type must be set to <literal>itemorder</literal> in
+ For Item Order, <literal>type</literal> must be set to
+ <literal>itemorder</literal> in
<function>ZOOM_package_send</function>.
</para>
<entry>none</entry>
</row>
<row>
+ <entry>itemorder-setname</entry>
+ <entry>Name of result set for record</entry>
+ <entry>default</entry>
+ </row>
+ <row>
<entry>itemorder-item</entry>
<entry>Position for item (record) requested. An integer</entry>
<entry>1</entry>
</tbody>
</tgroup>
</table>
+ <para>
+ There are two variants of item order: ILL-variant and
+ XML document variant. In order to use the XML variant the setting
+ <literal>doc</literal> must hold the XML item order document. If that
+ setting is unset, the ILL-variant is used.
+ </para>
+
+ <table frame="top" id="zoom.illrequest.options">
+ <title>ILL Request Options</title>
+ <tgroup cols="1">
+ <colspec colwidth="4*" colname="name"></colspec>
+ <thead>
+ <row>
+ <entry>Option</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row><entry>protocol-version-num</entry></row>
+ <row><entry>transaction-id,initial-requester-id,person-or-institution-symbol,person</entry></row>
+ <row><entry>transaction-id,initial-requester-id,person-or-institution-symbol,institution</entry></row>
+ <row><entry>transaction-id,initial-requester-id,name-of-person-or-institution,name-of-person</entry></row>
+ <row><entry>transaction-id,initial-requester-id,name-of-person-or-institution,name-of-institution</entry></row>
+ <row><entry>transaction-id,transaction-group-qualifier</entry></row>
+ <row><entry>transaction-id,transaction-qualifier</entry></row>
+ <row><entry>transaction-id,sub-transaction-qualifier</entry></row>
+ <row><entry>service-date-time,this,date</entry></row>
+ <row><entry>service-date-time,this,time</entry></row>
+ <row><entry>service-date-time,original,date</entry></row>
+ <row><entry>service-date-time,original,time</entry></row>
+ <row><entry>requester-id,person-or-institution-symbol,person</entry></row>
+ <row><entry>requester-id,person-or-institution-symbol,institution</entry></row>
+ <row><entry>requester-id,name-of-person-or-institution,name-of-person</entry></row>
+ <row><entry>requester-id,name-of-person-or-institution,name-of-institution</entry></row>
+ <row><entry>responder-id,person-or-institution-symbol,person</entry></row>
+ <row><entry>responder-id,person-or-institution-symbol,institution</entry></row>
+ <row><entry>responder-id,name-of-person-or-institution,name-of-person</entry></row>
+ <row><entry>responder-id,name-of-person-or-institution,name-of-institution</entry></row>
+ <row><entry>transaction-type</entry></row>
+ <row><entry>delivery-address,postal-address,name-of-person-or-institution,name-of-person</entry></row>
+ <row><entry>delivery-address,postal-address,name-of-person-or-institution,name-of-institution</entry></row>
+ <row><entry>delivery-address,postal-address,extended-postal-delivery-address</entry></row>
+ <row><entry>delivery-address,postal-address,street-and-number</entry></row>
+ <row><entry>delivery-address,postal-address,post-office-box</entry></row>
+ <row><entry>delivery-address,postal-address,city</entry></row>
+ <row><entry>delivery-address,postal-address,region</entry></row>
+ <row><entry>delivery-address,postal-address,country</entry></row>
+ <row><entry>delivery-address,postal-address,postal-code</entry></row>
+ <row><entry>delivery-address,electronic-address,telecom-service-identifier</entry></row>
+ <row><entry>delivery-address,electronic-address,telecom-service-addreess</entry></row>
+ <row><entry>billing-address,postal-address,name-of-person-or-institution,name-of-person</entry></row>
+ <row><entry>billing-address,postal-address,name-of-person-or-institution,name-of-institution</entry></row>
+ <row><entry>billing-address,postal-address,extended-postal-delivery-address</entry></row>
+ <row><entry>billing-address,postal-address,street-and-number</entry></row>
+ <row><entry>billing-address,postal-address,post-office-box</entry></row>
+ <row><entry>billing-address,postal-address,city</entry></row>
+ <row><entry>billing-address,postal-address,region</entry></row>
+ <row><entry>billing-address,postal-address,country</entry></row>
+ <row><entry>billing-address,postal-address,postal-code</entry></row>
+ <row><entry>billing-address,electronic-address,telecom-service-identifier</entry></row>
+ <row><entry>billing-address,electronic-address,telecom-service-addreess</entry></row>
+ <row><entry>ill-service-type</entry></row>
+ <row><entry>requester-optional-messages,can-send-RECEIVED</entry></row>
+ <row><entry>requester-optional-messages,can-send-RETURNED</entry></row>
+ <row><entry>requester-optional-messages,requester-SHIPPED</entry></row>
+ <row><entry>requester-optional-messages,requester-CHECKED-IN</entry></row>
+ <row><entry>search-type,level-of-service</entry></row>
+ <row><entry>search-type,need-before-date</entry></row>
+ <row><entry>search-type,expiry-date</entry></row>
+ <row><entry>search-type,expiry-flag</entry></row>
+ <row><entry>place-on-hold</entry></row>
+ <row><entry>client-id,client-name</entry></row>
+ <row><entry>client-id,client-status</entry></row>
+ <row><entry>client-id,client-identifier</entry></row>
+ <row><entry>item-id,item-type</entry></row>
+ <row><entry>item-id,call-number</entry></row>
+ <row><entry>item-id,author</entry></row>
+ <row><entry>item-id,title</entry></row>
+ <row><entry>item-id,sub-title</entry></row>
+ <row><entry>item-id,sponsoring-body</entry></row>
+ <row><entry>item-id,place-of-publication</entry></row>
+ <row><entry>item-id,publisher</entry></row>
+ <row><entry>item-id,series-title-number</entry></row>
+ <row><entry>item-id,volume-issue</entry></row>
+ <row><entry>item-id,edition</entry></row>
+ <row><entry>item-id,publication-date</entry></row>
+ <row><entry>item-id,publication-date-of-component</entry></row>
+ <row><entry>item-id,author-of-article</entry></row>
+ <row><entry>item-id,title-of-article</entry></row>
+ <row><entry>item-id,pagination</entry></row>
+ <row><entry>item-id,ISBN</entry></row>
+ <row><entry>item-id,ISSN</entry></row>
+ <row><entry>item-id,additional-no-letters</entry></row>
+ <row><entry>item-id,verification-reference-source</entry></row>
+ <row><entry>copyright-complicance</entry></row>
+ <row><entry>retry-flag</entry></row>
+ <row><entry>forward-flag</entry></row>
+ <row><entry>requester-note</entry></row>
+ <row><entry>forward-note</entry></row>
+ </tbody>
+ </tgroup>
+ </table>
</sect2>
<sect2 id="zoom.record.update">
<title>Record Update</title>
<para>
- For Record Update, type must be set to <literal>update</literal> in
+ For Record Update, <literal>type</literal> must be set to
+ <literal>update</literal> in
<function>ZOOM_package_send</function>.
</para>
<table frame="top" id="zoom.record.update.options">
Option <literal>recordOpaque</literal> is an alternative
to record - and <literal>record</literal> option (above) is
ignored if recordOpaque is set. This option is only available in
- YAZ 3.0.35 and later and is meant to facilitate Updates with
+ YAZ 3.0.35 and later, and is meant to facilitate Updates with
servers from OCLC.
</entry>
<entry>none</entry>
<sect2 id="zoom.database.create"><title>Database Create</title>
<para>
- For Database Create, type must be set to <literal>create</literal> in
+ For Database Create, <literal>type</literal> must be set to
+ <literal>create</literal> in
<function>ZOOM_package_send</function>.
</para>
<sect2 id="zoom.database.drop">
<title>Database Drop</title>
<para>
- For Database Drop, type must be set to <literal>drop</literal> in
+ For Database Drop, <literal>type</literal> must be set to
+ <literal>drop</literal> in
<function>ZOOM_package_send</function>.
</para>
<table frame="top" id="zoom.database.drop.options">
<sect2 id="zoom.commit">
<title>Commit Operation</title>
<para>
- For Commit, type must be set to <literal>commit</literal> in
+ For Commit, <literal>type</literal> must be set to
+ <literal>commit</literal> in
<function>ZOOM_package_send</function>.
</para>
</sect2>
</para>
<note>
<para>
- The database create, drop and commit services are privately defined
+ The database create, drop, and commit services are privately defined
operations.
Refer to <filename>esadmin.asn</filename> in YAZ for the ASN.1
definitions.
<title>Options</title>
<para>
Most &zoom; objects provide a way to specify options to change behavior.
- From an implementation point of view a set of options is just like
+ From an implementation point of view, a set of options is just like
an associative array / hash.
</para>
<synopsis>
<para>
<function>ZOOM_query_cql2rpn</function> translates the CQL string,
client-side, into RPN which may be passed to the server.
- This is useful for server's that don't themselves
+ This is useful for servers that don't themselves
support CQL, for which <function>ZOOM_query_cql</function> is useless.
- `conn' is used only as a place to stash diagnostics if compilation
+ 'conn' is used only as a place to stash diagnostics if compilation
fails; if this information is not needed, a null pointer may be used.
The CQL conversion is driven by option <literal>cqlfile</literal> from
- connection conn. This specifies a conversion file (eg pqf.properties)
+ connection conn. This specifies a conversion file (e.g. pqf.properties)
which <emphasis>must</emphasis> be present.
</para>
<para>
client-side, into RPN which may be passed to the server.
The conversion is driven by the specification given by
<literal>config</literal>. Upon completion 0 is returned on success; -1
- is returned on on failure. Om failure <literal>error_string</literal> and
- <literal>error_pos</literal> holds error message and position of
+ is returned on failure. On failure <literal>error_string</literal> and
+ <literal>error_pos</literal> hold the error message and position of
first error in original CCL string.
</para>
</sect1>
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,
+ A pending event could be sending a search, receiving a response,
etc.
When an event has occurred 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 ensure that all outstanding requests are performed call this function
+ To ensure that all outstanding requests are performed, call this function
repeatedly until zero is returned.
</para>
<para>
- If <function>ZOOM_event</function> returns and returns non-zero, the
+ If <function>ZOOM_event</function> returns, and returns non-zero, the
last event that occurred can be expected.
</para>
<synopsis>
</row>
<row>
<entry>ZOOM_EVENT_RECV_DATA</entry>
- <entry>Data has been received)</entry>
+ <entry>Data has been received</entry>
</row>
<row>
<entry>ZOOM_EVENT_TIMEOUT</entry>
</row>
<row>
<entry>ZOOM_EVENT_RECV_SEARCH</entry>
- <entry>A search result been received</entry>
+ <entry>A search result has been received</entry>
</row>
</tbody>
</tgroup>
</para>
<para>
If you have a database system that you would like to make available by
- means of Z39.50 or SRU, &yaz; basically offers your two options. You
+ means of Z39.50 or SRU, &yaz; basically offers two options. You
can use the APIs provided by the &asn;, &odr;, and &comstack;
modules to
create and decode PDUs, and exchange them with a client.
<listitem><para>
A boolean value, which determines whether the server
will fork on each incoming request (TRUE), or not (FALSE). Default is
- TRUE. This flag is only read by UNIX-based servers (WIN32 based servers
- doesn't fork).
+ TRUE. This flag is only read by UNIX-based servers (WIN32-based servers
+ do not fork).
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>int inetd</literal></term>
<listitem><para>
A boolean value, which determines whether the server
- will operates under a UNIX INET daemon (inetd). Default is FALSE.
+ will operate under a UNIX INET daemon (inetd). Default is FALSE.
</para></listitem>
</varlistentry>
<varlistentry>
<listitem><para>Pointer to function which is called after the
command line options have been parsed - but before the server
starts listening.
- For forked UNIX servers this handler is called in the mother
- process; for threaded servers this handler is called in the
+ For forked UNIX servers, this handler is called in the mother
+ process; for threaded servers, this handler is called in the
main thread.
The default value of this pointer is NULL in which case it
isn't invoked by the frontend server.
- When the server operates as an NT service this handler is called
+ When the server operates as an NT service, this handler is called
whenever the service is started.
</para></listitem>
</varlistentry>
<listitem><para>Pointer to function which is called whenever the server
has stopped listening for incoming connections. This function pointer
has a default value of NULL in which case it isn't called.
- When the server operates as an NT service this handler is called
+ When the server operates as an NT service, this handler is called
whenever the service is stopped.
</para></listitem>
</varlistentry>
<para>
The pointer returned by <literal>statserv_getcontrol</literal> points to
a static area. You are allowed to change the contents of the structure,
- but the changes will not take effect before you call
+ but the changes will not take effect until you call
</para>
<synopsis>
void statserv_setcontrol(statserv_options_block *block);
</synopsis>
<note>
<para>
- that you should generally update this structure before calling
+ You should generally update this structure before calling
<function>statserv_main()</function>.
</para>
</note>
<para>
Unlike previous versions of YAZ, the <function>bend_init</function> also
serves as a handler that defines the Z39.50 services that the backend
- wish to support. Pointers to <emphasis>all</emphasis> service handlers,
+ intends to support. Pointers to <emphasis>all</emphasis> service handlers,
including search - and fetch must be specified here in this handler.
</para>
<para>
</para>
<para>
The <literal>auth</literal> member holds the authentication information
- part of the Z39.50 Initialize Request. Interpret this if your serves
+ part of the Z39.50 Initialize Request. Interpret this if your server
requires authentication.
</para>
<para>
</synopsis>
<para>
The <function>bend_search</function> handler is a fairly close
- approximation of a protocol Z39.50 Search Request - and Response PDUs
+ approximation of a protocol Z39.50 Search Request - and Response PDUs.
The <literal>setname</literal> is the resultSetName from the protocol.
You are required to establish a mapping between the set name and whatever
your backend database likes to use.
<sect2 id="server.delete">
<title>Delete</title>
<para>
- For back-ends that supports delete of a result set only one handler
+ For back-ends that supports delete of a result set, only one handler
must be defined.
</para>
<synopsis>
<para>
This backend server handles both Z39.50 scan
and SRU scan. In order for a handler to distinguish between SRU (CQL) scan
- Z39.50 Scan , it must check for a non-NULL value of
+ Z39.50 Scan, it must check for a non-NULL value of
<literal>scanClause</literal>.
</para>
<note>
<para>
- if designed today, it would be a choice using a union or similar,
+ If designed today, it would be a choice using a union or similar,
but that would break binary compatibility with existing servers.
</para>
</note>
</screen>
</para>
<para>
- The above for the Apache 1.3 series.
+ The above is for the Apache 1.3 series.
</para>
</example>
<example id="server.example.local.access">
<title>Running a server with local access only</title>
<para>
- Servers that is only being accessed from the local host should listen
- on UNIX file socket rather than a Internet socket. To listen on
+ A server that is only being accessed from the local host should listen
+ on UNIX file socket rather than an Internet socket. To listen on
<filename>/tmp/mysocket</filename> start the server as follows:
<screen>
application unix:/tmp/mysocket
</para>
<para>
The &asn; module is located in sub directory <filename>z39.50</filename>.
- There you'll find C files that implements encoders and decoders for the
+ There you'll find C files that implement encoders and decoders for the
Z39.50 types. You'll also find the protocol definitions:
<filename>z3950v3.asn</filename>, <filename>esupdate.asn</filename>,
and others.
<xref linkend="odr.use"/> for details). When you use
<function>odr_malloc()</function>, you can release all of the
allocated data in a single operation, independent of any pointers and
- relations between the data. <function>odr_malloc()</function> is based on a
- "nibble-memory"
+ relations between the data. The <function>odr_malloc()</function> function
+ is based on a "nibble-memory"
scheme, in which large portions of memory are allocated, and then
gradually handed out with each call to <function>odr_malloc()</function>.
The next time you call <function>odr_reset()</function>, all of the
Z_<type> *zget_<type>(ODR o);
</synopsis>
<para>
- eg.:
+ e.g.:
</para>
<synopsis>
Z_InitRequest *zget_InitRequest(ODR o);
<literal>octet_aligned</literal> arm of the union.
</para>
<para>
- Some servers return ASN.1 structured data values (eg. database
+ Some servers return ASN.1 structured data values (e.g. database
records) as BER-encoded records placed in the
<literal>octet-aligned</literal> branch of the EXTERNAL CHOICE.
The ASN-module will <emphasis>not</emphasis> automatically decode
Z_ext_typeent *z_ext_gettypebyref(const oid *oid);
</screen>
<para>
- Can be used to retrieve information about the known, external data
- types. The function return a pointer to a static area, or NULL, if no
+ can be used to retrieve information about the known, external data
+ types. The function returns a pointer to a static area, or NULL, if no
match for the given direct reference is found. The
<literal>Z_ext_typeent</literal>
is defined as:
</para>
<para>
If you want to <emphasis>send</emphasis> EXTERNALs containing
- ASN.1-structured values in the occtet-aligned branch of the CHOICE, this
+ ASN.1-structured values in the octet-aligned branch of the CHOICE, this
is possible too. However, on the encoding phase, it requires a somewhat
involved juggling around of the various buffers involved.
</para>
<title>Introduction</title>
<para>
&yaz; uses a very simple implementation of
- <ulink url="&url.soap;">SOAP</ulink> that only,
- currenly, supports what is sufficient to offer SRU SOAP functionality.
+ <ulink url="&url.soap;">SOAP</ulink> that only
+ (currently) supports what is sufficient to offer SRU SOAP functionality.
The implementation uses the
<ulink url="&url.libxml2.api.tree;">tree API</ulink> of
libxml2 to encode and decode SOAP packages.
</para>
<para>
The <literal>fault</literal> and <literal>soap_error</literal>
- arms represent both a SOAP fault - struct
+ arms both represent a SOAP fault - struct
<literal>Z_SOAP_Fault</literal>. Any other generic
(valid) package is represented by <literal>Z_SOAP_Generic</literal>.
</para>
When decoding, the <function>z_soap_codec</function>
inspects the XML content
and tries to match one of the services namespaces of the
- supplied handlers. If there is a match a handler function
+ supplied handlers. If there is a match. a handler function
is invoked which decodes that particular SOAP package.
If successful, the returned <literal>Z_SOAP</literal> package will be
of type <literal>Z_SOAP_Generic</literal>.
Member <literal>no</literal> is
- set the offset of handler that matched; <literal>ns</literal>
- is set to namespace of matching handler; the void pointer
+ set the offset of the handler that matched; <literal>ns</literal>
+ is set to namespace of the matching handler; the void pointer
<literal>p</literal> is set to the C data structure assocatiated
with the handler.
</para>
<para>
- When a NULL namespace is met (member <literal>ns</literal> bwlow),
+ When a NULL namespace is met (member <literal>ns</literal> below),
that specifies end-of-list.
</para>
<para>
Z_SOAP_fun f;
} Z_SOAP_Handler;
</synopsis>
- The <literal>ns</literal> is namespace of service associated with
- handler <literal>f</literal>. <literal>client_data</literal>
- is user-defined data which is passed to handler.
+ The <literal>ns</literal> is the namespace of the service associated with
+ handler <literal>f</literal>. The <literal>client_data</literal>
+ is user-defined data which is passed to the handler.
</para>
<para>
The prototype for a SOAP service handler is:
is a libxml2 tree node pointer (<literal>xmlNodePtr</literal>)
and is a pointer to the <literal>Body</literal> element
of the SOAP package. The <parameter>handler_data</parameter>
- is an opaque pointer to a C definitions associated with the
- SOAP service. <parameter>client_data</parameter> is the pointer
+ is an opaque pointer to C definitions associated with the
+ SOAP service. The <parameter>client_data</parameter> is the pointer
which was set as part of the <literal>Z_SOAP_handler</literal>.
- Finally, <parameter>ns</parameter> the service namespace.
+ Finally, <parameter>ns</parameter> is the service namespace.
</para>
</sect1>
<sect1 id="soap.srw">
Please observe that data of type xsd:string is represented
as a char pointer (<literal>char *</literal>). A null pointer
means that the element is absent.
- Data of type xsd:integer is representd as a pointer to
+ Data of type xsd:integer is represented as a pointer to
an int (<literal>int *</literal>). Again, a null pointer
- us used for absent elements.
+ is used for absent elements.
</para>
<para>
The SearchRetrieveResponse has the following definition.
} Z_SRW_searchRetrieveResponse;
</synopsis>
The <literal>num_records</literal> and <literal>num_diagnostics</literal>
- is number of returned records and diagnostics respectively and also
+ is number of returned records and diagnostics respectively, and also
correspond to the "size of" arrays <literal>records</literal>
and <literal>diagnostics</literal>.
</para>
<title>Supporting Tools</title>
<para>
In support of the service API - primarily the ASN module, which
- provides the pro-grammatic interface to the Z39.50 APDUs, &yaz; contains
+ provides the programmatic interface to the Z39.50 APDUs, &yaz; contains
a collection of tools that support the development of applications.
</para>
<sect1 id="tools.query">
</para>
<note>
<para>
- The PQF have been adopted by other parties developing Z39.50
+ The PQF has been adopted by other parties developing Z39.50
software. It is often referred to as Prefix Query Notation
- PQN.
</para>
</note>
<para>
The PQF is defined by the pquery module in the YAZ library.
- There are two sets of function that have similar behavior. First
+ There are two sets of functions that have similar behavior. First
set operates on a PQF parser handle, second set doesn't. First set
- set of functions are more flexible than the second set. Second set
+ of functions are more flexible than the second set. Second set
is obsolete and is only provided to ensure backwards compatibility.
</para>
<para>
A PQF parser is created and destructed by functions
<function>yaz_pqf_create</function> and
<function>yaz_pqf_destroy</function> respectively.
- Function <function>yaz_pqf_parse</function> parses query given
+ Function <function>yaz_pqf_parse</function> parses the query given
by string <literal>qbuf</literal>. If parsing was successful,
a Z39.50 RPN Query is returned which is created using ODR stream
<literal>o</literal>. If parsing failed, a NULL pointer is
Error information for bad queries can be obtained by a call to
<function>yaz_pqf_error</function> which returns an error code and
modifies <literal>*msg</literal> to point to an error description,
- and modifies <literal>*off</literal> to the offset within last
- query were parsing failed.
+ and modifies <literal>*off</literal> to the offset within the last
+ query where parsing failed.
</para>
<para>
The second set of functions are declared as follows:
a sub-query. The attribute type-value pair is packed in one string:
an attribute type, an equals sign, and an attribute value, like this:
<literal>@attr 1=1003</literal>.
- The type is always an integer but the value may be either an
+ The type is always an integer, but the value may be either an
integer or a string (if it doesn't start with a digit character).
- A string attribute-value is encoded as a Type-1 ``complex''
+ A string attribute-value is encoded as a Type-1 "complex"
attribute with the list of values containing the single string
specified, and including no semantic indicators.
</para>
<screen>
@prox <replaceable>exclusion</replaceable> <replaceable>distance</replaceable> <replaceable>ordered</replaceable> <replaceable>relation</replaceable> <replaceable>which-code</replaceable> <replaceable>unit-code</replaceable>
</screen>
- in which the meanings of the parameters are as described in in
+ in which the meanings of the parameters are as described in
the standard, and they can take the following values:
<itemizedlist>
<listitem>
or
<literal>k</literal>
(the unit-code parameter is taken from the well-known list
- of alternatives described in below) or
+ of alternatives described below) or
<literal>private</literal>
or
<literal>p</literal>
- (the unit-code paramater has semantics specific to an
+ (the unit-code parameter has semantics specific to an
out-of-band agreement such as a profile).
</para>
</formalpara>
</listitem>
<listitem>
<para>
- which-code is ``known'', so the standard unit-codes are used
+ which-code is "known", so the standard unit-codes are used
</para>
</listitem>
<listitem>
<literal>dylan</literal> and <literal>zimmerman</literal> must
both occur in the record, in that order, differing in position
by three or fewer words (i.e. with two or fewer words between
- them.) The query would find ``Bob Dylan, aka. Robert
- Zimmerman'', but not ``Bob Dylan, born as Robert Zimmerman''
+ them.) The query would find "Bob Dylan, aka. Robert
+ Zimmerman", but not "Bob Dylan, born as Robert Zimmerman"
since the distance in this case is four.
</para>
</example>
access point
2038 indicates West Bounding Coordinate and
2030 indicates East Bounding Coordinate,
- so the query is for areas extending from -114 degrees
- to no more than -109 degrees.
+ so the query is for areas extending from -114 degrees longitude
+ to no more than -109 degrees longitude.
</para>
</example>
</sect3>
<title>CCL Syntax</title>
<para>
The CCL parser obeys the following grammar for the FIND argument.
- The syntax is annotated by in the lines prefixed by
+ The syntax is annotated using lines prefixed by
<literal>--</literal>.
</para>
<screen>
singlechar#mask
</screen>
<para>
- Assuming that the qualifiers <literal>ti</literal>,
- <literal>au</literal>
- and <literal>date</literal> are defined we may use:
+ Assuming that the qualifiers <literal>ti</literal>
+ and <literal>au</literal>
+ and <literal>date</literal> are defined, we may use:
</para>
<screen>
ti=self portrait
</para>
<para>
where <replaceable>qualifier-name</replaceable> is the name of the
- qualifier to be used (eg. <literal>ti</literal>),
+ qualifier to be used (e.g. <literal>ti</literal>),
<replaceable>type</replaceable> is attribute type in the attribute
set (Bib-1 is used if no attribute set is given) and
<replaceable>val</replaceable> is attribute value.
The <replaceable>type</replaceable> can be specified as an
- integer or as it be specified either as a single-letter:
+ integer, or as a single-letter:
<literal>u</literal> for use,
- <literal>r</literal> for relation,<literal>p</literal> for position,
- <literal>s</literal> for structure,<literal>t</literal> for truncation
+ <literal>r</literal> for relation, <literal>p</literal> for position,
+ <literal>s</literal> for structure,<literal>t</literal> for truncation,
or <literal>c</literal> for completeness.
The attributes for the special qualifier name <literal>term</literal>
are used when no CCL qualifier is given in a query.
<entry>
Use attribute (1). Common use attributes are
1 Personal-name, 4 Title, 7 ISBN, 8 ISSN, 30 Date,
- 62 Subject, 1003 Author), 1016 Any. Specify value
+ 62 Subject, 1003 Author, 1016 Any. Specify value
as an integer.
</entry>
</row>
<entry><literal>t=</literal><replaceable>value</replaceable></entry>
<entry>
Truncation attribute (5). Values: 1 right, 2 left,
- 3 left& right, 100 none, 101 process #, 102 regular-1,
+ 3 left and right, 100 none, 101 process #, 102 regular-1,
103 regular-2, 104 CCL.
</entry>
</row>
<row>
<entry><literal>s=al</literal></entry>
<entry>
- Each token in the term is ANDed. (and-list).
+ Each token in the term is ANDed (and-list).
This does not set the structure at all.
</entry>
</row>
<row><entry><literal>s=ol</literal></entry>
<entry>
- Each token in the term is ORed. (or-list).
+ Each token in the term is ORed (or-list).
This does not set the structure at all.
</entry>
</row>
in YAZ 4.2.38.
</entry>
</row>
+ <row><entry><literal>s=sl</literal></entry>
+ <entry>
+ Tokens are split into sub-phrases of all combinations - in order.
+ This facility appeared in YAZ 5.14.0.
+ </entry>
+ </row>
<row><entry><literal>r=o</literal></entry>
<entry>
- Allows ranges and the operators greather-than, less-than, ...
+ Allows ranges and the operators greater-than, less-than, ...
equals.
This sets Bib-1 relation attribute accordingly (relation
ordered). A query construct is only treated as a range if
<row><entry><literal>r=omiteq</literal></entry>
<entry>
This will omit relation=equals (@attr 2=3) when r=o / r=r
- is used. This is useful for servers that somehow breaks
+ is used. This is useful for servers that somehow break
when an explicit relation=equals is used. Omitting the
relation is usually safe because "equals" is the default
behavior. This tweak was added in YAZ version 5.1.2.
</row>
<row><entry><literal>t=b</literal></entry>
<entry>
- Allows term to be both left&right truncated.
+ Allows term to be both left-and-right truncated.
If term is of the form <literal>?x?</literal>, the
resulting term is <literal>x</literal> and trunctation is
- set to both left&right.
+ set to both left and right.
</entry>
</row>
<row><entry><literal>t=x</literal></entry>
<entry>
Allows masking anywhere in a term, thus fully supporting
# (mask one character) and ? (zero or more of any).
- If masking is used, trunction is set to 102 (regexp-1 in term)
+ If masking is used, truncation is set to 102 (regexp-1 in term)
and the term is converted accordingly to a regular expression.
</entry>
</row>
<entry>
Allows masking anywhere in a term, thus fully supporting
# (mask one character) and ? (zero or more of any).
- If masking is used, trunction is set to 104 (Z39.58 in term)
+ If masking is used, truncation is set to 104 (Z39.58 in term)
and the term is converted accordingly to Z39.58 masking term -
actually the same truncation as CCL itself.
</entry>
<literal>ti</literal>
sets the use-attribute to 4. <literal>au</literal> sets the
use-attribute to 1.
- When no qualifiers are used in the query the structure-attribute is
+ When no qualifiers are used in the query, the structure-attribute is
set to free-form-text (105) (rule for <literal>term</literal>).
The <literal>date</literal> sets the relation attribute to
the relation used in the CCL query and sets the use attribute
<para>
which takes the CCL profile (<literal>bibset</literal>) and query
(<literal>str</literal>) as input. Upon successful completion the RPN
- tree is returned. If an error occur, such as a syntax error, the integer
+ tree is returned. If an error occurs, such as a syntax error, the integer
pointed to by <literal>error</literal> holds the error code and
<literal>pos</literal> holds the offset inside query string in which
the parsing failed.
int cql_parser_stdio(CQL_parser cp, FILE *f);
</synopsis>
The functions <function>cql_parser_stream</function> and
- <function>cql_parser_stdio</function> parses a CQL query
+ <function>cql_parser_stdio</function> parse a CQL query
- just like <function>cql_parser_string</function>.
The only difference is that the CQL query can be
fed to the parser in different ways.
<sect3 id="cql.tree">
<title>CQL tree</title>
<para>
- The the query string is valid, the CQL parser
+ If the query string is valid, the CQL parser
generates a tree representing the structure of the
CQL query.
</para>
<synopsis>
struct cql_node *cql_parser_result(CQL_parser cp);
</synopsis>
- <function>cql_parser_result</function> returns the
+ <function>cql_parser_result</function> returns
a pointer to the root node of the resulting tree.
</para>
<para>
error-code and sets the string-pointer at
<literal>*addinfop</literal> to point to a string containing
additional information about the error that occurred: for
- example, if the error code is 15 (``Illegal or unsupported context
- set''), the additional information is the name of the requested
+ example, if the error code is 15 ("Illegal or unsupported context
+ set"), the additional information is the name of the requested
context set that was not recognised.
</para>
<para>
Typically, the RPN specifies an equivalent use attribute.
</para>
<para>
- For terms not bound by an index the pattern
+ For terms not bound by an index, the pattern
<literal>index.cql.serverChoice</literal> is used.
Here, the prefix <literal>cql</literal> is defined as
<literal>http://www.loc.gov/zing/cql/cql-indexes/v1.0/</literal>.
<listitem>
<para>
This pattern specifies how a CQL relation is mapped to RPN.
- <replaceable>pattern</replaceable> is name of relation
+ The <replaceable>pattern</replaceable> is name of relation
operator. Since <literal>=</literal> is used as
separator between CQL pattern and RPN, CQL relations
including <literal>=</literal> cannot be
<listitem>
<para>
This pattern specifies how a CQL structure is mapped to RPN.
- Note that this CQL pattern is somewhat to similar to
+ Note that this CQL pattern is somewhat similar to
CQL pattern <literal>relation</literal>.
The <replaceable>type</replaceable> is a CQL relation.
</para>
<para>
Conversion from CQL to XCQL is trivial and does not
require a mapping to be defined.
- There three functions to choose from depending on the
+ There are three functions to choose from depending on the
way you wish to store the resulting output (XML buffer
containing XCQL).
<synopsis>
void cql_to_xml_stdio(struct cql_node *cn, FILE *f);
</synopsis>
Function <function>cql_to_xml_buf</function> converts
- to XCQL and stores result in a user supplied buffer of a given
+ to XCQL and stores the result in a user-supplied buffer of a given
max size.
</para>
<para>
<function>cql_to_xml</function> writes the result in
- a user defined output stream.
+ a user-defined output stream.
<function>cql_to_xml_stdio</function> writes to a
a file.
</para>
</para>
<para>
An OID can either be declared as a automatic variable or it can
- allocated using the memory utilities or ODR/NMEM. It's
+ be allocated using the memory utilities or ODR/NMEM. It's
guaranteed that an OID can fit in <literal>OID_SIZE</literal> integers.
</para>
<example id="tools.oid.bib1.1"><title>Create OID on stack</title>
</example>
<para>
And OID may also be filled from a string-based representation using
- dots (.). This is achieved by function
+ dots (.). This is achieved by the function
<screen>
int oid_dotstring_to_oid(const char *name, Odr_oid *oid);
</screen>
</para>
<example id="tools.oid.bib1.2"><title>Using oid_oiddotstring_to_oid</title>
<para>
- We can fill the Bib-1 attribute set OID easier with:
+ We can fill the Bib-1 attribute set OID more easily with:
<screen>
Odr_oid bib1[OID_SIZE];
oid_oiddotstring_to_oid("1.2.840.10003.3.1", bib1);
</para>
</example>
<para>
- We can also allocate an OID dynamically on a ODR stream with:
+ We can also allocate an OID dynamically on an ODR stream with:
<screen>
Odr_oid *odr_getoidbystr(ODR o, const char *str);
</screen>
- This creates an OID from string-based representation using dots.
+ This creates an OID from a string-based representation using dots.
This function take an &odr; stream as parameter. This stream is used to
allocate memory for the data elements, which is released on a
subsequent call to <function>odr_reset()</function> on that stream.
<example id="tools.oid.bib1.3">
<title>Using odr_getoidbystr</title>
<para>
- We can create a OID for the Bib-1 attribute set with:
+ We can create an OID for the Bib-1 attribute set with:
<screen>
Odr_oid *bib1 = odr_getoidbystr(odr, "1.2.840.10003.3.1");
</screen>
</para>
<para>
OIDs can be copied with <function>oid_oidcpy</function> which takes
- two OID lists as arguments. Alternativly, an OID copy can be allocated
- on a ODR stream with:
+ two OID lists as arguments. Alternatively, an OID copy can be allocated
+ on an ODR stream with:
<screen>
Odr_oid *odr_oiddup(ODR odr, const Odr_oid *o);
</screen>
</para>
<para>
A YAZ database handle is of type <literal>yaz_oid_db_t</literal>.
- Actually that's a pointer. You need not think deal with that.
+ Actually that's a pointer. You need not deal with that.
YAZ has a built-in database which can be considered "constant" for
most purposes.
- We can get hold that by using function <function>yaz_oid_std</function>.
+ We can get hold of that by using function <function>yaz_oid_std</function>.
</para>
<para>
All functions with prefix <function>yaz_string_to_oid</function>
<title>Standard OIDs</title>
<para>
All the object identifers in the standard OID database as returned
- by <function>yaz_oid_std</function> can referenced directly in a
+ by <function>yaz_oid_std</function> can be referenced directly in a
program as a constant OID.
Each constant OID is prefixed with <literal>yaz_oid_</literal> -
followed by OID class (lowercase) - then by OID name (normalized and
Z39.50 PDUs and related structures, it is convenient to use the
memory-management system of the &odr; subsystem (see
<xref linkend="odr.use"/>). However, in some circumstances
- where you might otherwise benefit from using a simple nibble memory
+ where you might otherwise benefit from using a simple nibble-memory
management system, it may be impractical to use
<function>odr_malloc()</function> and <function>odr_reset()</function>.
For this purpose, the memory manager which also supports the &odr;
allocated on the handle.
</para>
<para>
- The nibble memory pool is shared amongst threads. POSIX
+ The nibble-memory pool is shared amongst threads. POSIX
mutex'es and WIN32 Critical sections are introduced to keep the
module thread safe. Function <function>nmem_init()</function>
- initializes the nibble memory library and it is called automatically
+ initializes the nibble-memory library and it is called automatically
the first time the <literal>YAZ.DLL</literal> is loaded. &yaz; uses
function <function>DllMain</function> to achieve this. You should
<emphasis>not</emphasis> call <function>nmem_init</function> or
and implemented in <filename>src/log.c</filename>.
Due to name clash with syslog and some math utilities the logging
interface has been modified as of YAZ 2.0.29. The obsolete interface
- is still available if in header file <filename>yaz/log.h</filename>.
+ is still available in header file <filename>yaz/log.h</filename>.
The key points of the interface are:
</para>
<screen>
passed to <function>yaz_log_init_level</function> for it to take effect.
</para>
<para>
- Each module should check what log bits it should be used, by calling
+ Each module should check what log bits should be used, by calling
<function>yaz_log_module_level</function> with a suitable name for the
- module. The name is cleared from a preceding path and an extension, if any,
+ module. The name is cleared of a preceding path and an extension, if any,
so it is quite possible to use <literal>__FILE__</literal> for it. If the
name has been passed to <function>yaz_log_mask_str</function>, the routine
returns a non-zero bitmask, which should then be used in consequent calls
<literal>malloc, nmem, odr, eventl</literal> for internal
debugging of yaz itself.
Of course, any program using yaz is welcome to define as many new
- ones, as it needs.
+ ones as it needs.
</para>
<para>
By default the log is written to stderr, but this can be changed by a call
<para>
YAZ provides a fast utility for working with MARC records.
Early versions of the MARC utility only allowed decoding of ISO2709.
- Today the utility may both encode - and decode to a varity of formats.
+ Today the utility may both encode - and decode to a variety of formats.
</para>
<synopsis><![CDATA[
#include <yaz/marcdisp.h>
by calling <function>yaz_marc_destroy</function>.
</para>
<para>
- All other function operate on a <literal>yaz_marc_t</literal> handle.
+ All other functions operate on a <literal>yaz_marc_t</literal> handle.
The output is specified by a call to <function>yaz_marc_xml</function>.
The <literal>xmlmode</literal> must be one of
<variablelist>
<listitem>
<para>
A simple line-by-line format suitable for display but not
- recommend for further (machine) processing.
+ recommended for further (machine) processing.
</para>
</listitem>
</varlistentry>
<term>YAZ_MARC_JSON</term>
<listitem>
<para>
- <ulink url="&url.marc_in_json;">MARC-in_JSON</ulink> format.
+ <ulink url="&url.marc_in_json;">MARC-in-JSON</ulink> format.
</para>
</listitem>
</varlistentry>
The actual conversion functions are
<function>yaz_marc_decode_buf</function> and
<function>yaz_marc_decode_wrbuf</function> which decodes and encodes
- a MARC record. The former function operates on simple buffers, the
+ a MARC record. The former function operates on simple buffers, and
stores the resulting record in a WRBUF handle (WRBUF is a simple string
type).
</para>
<para>
Applications like
Pazpar2 uses XSLT to convert an XML encoded MARC record to an internal
- representation. This conversion mostly check the tag of a MARC field
+ representation. This conversion mostly checks the tag of a MARC field
to determine the basic rules in the conversion. This check is
- costly when that is tag is encoded as an attribute in MARCXML.
+ costly when that tag is encoded as an attribute in MARCXML.
By having the tag value as the element instead, makes processing
many times faster (at least for Libxslt).
</para>
A control field is encoded as element <literal>c</literal> concatenated
with the tag value of the control field if the tag value
matches the regular expression <literal>[a-zA-Z0-9]*</literal>.
- If the tag value do not match the regular expression
+ If the tag value does not match the regular expression
<literal>[a-zA-Z0-9]*</literal> the control field is encoded
as element <literal>c</literal> and attribute <literal>code</literal>
will hold the tag value.
- This rule ensure that in the rare cases where a tag value might
- result in a non-wellformed XML YAZ encode it as a coded attribute
+ This rule ensures that in the rare cases where a tag value might
+ result in a non-well-formed XML, then YAZ will encode it as a coded attribute
(as in MARCXML).
</para>
<para>
- The control field content is the the text value of this element.
+ The control field content is the text value of this element.
Indicators are encoded as attribute names
- <literal>i1</literal>, <literal>i2</literal>, etc.. and
+ <literal>i1</literal>, <literal>i2</literal>, etc. and
corresponding values for each indicator.
</para>
</listitem>
A data field is encoded as element <literal>d</literal> concatenated
with the tag value of the data field or using the attribute
<literal>code</literal> as described in the rules for control fields.
- The children of the data field element is subfield elements.
+ The children of the data field element are subfield elements.
Each subfield element is encoded as <literal>s</literal>
concatenated with the sub field code.
The text of the subfield element is the contents of the subfield.
- Indicators are encoded as attributes for the data field element similar
+ Indicators are encoded as attributes for the data field element, similar
to the encoding for control fields.
</para>
</listitem>
The Retrieval facility is driven by an XML configuration. The
configuration is neither Z39.50 ZeeRex or SRU ZeeRex. But it
should be easy to generate both of them from the XML configuration.
- (unfortunately the two versions
- of ZeeRex differ substantially in this regard).
+ (Unfortunately the two versions
+ of ZeeRex differ substantially in this regard.)
</para>
<sect2 id="tools.retrieval.format">
<title>Retrieval XML format</title>
<listitem>
<para>
Defines the name of the retrieval format. This can be
- any string. For SRU, the value, is equivalent to schema (short-hand);
+ any string. For SRU, the value is equivalent to schema (short-hand);
for Z39.50 it's equivalent to simple element set name.
For YAZ 3.0.24 and later this name may be specified as a glob
expression with operators
<listitem>
<para>
Defines the URI schema name of the retrieval format. This can be
- any string. For SRU, the value, is equivalent to URI schema.
+ any string. For SRU, the value is equivalent to URI schema.
For Z39.50, there is no equivalent.
</para>
</listitem>
</para>
<para>
The attributes, <literal>name</literal> and <literal>syntax</literal>
- may be specified for the <literal>backend</literal> element. These
+ may be specified for the <literal>backend</literal> element. The
semantics of these attributes is equivalent to those for the
<literal>retrieval</literal>. However, these values are passed to
the "backend".
</para>
<para>
- The <literal>backend</literal> element may includes one or more
+ The <literal>backend</literal> element may include one or more
conversion instructions (as children elements). The supported
conversions are:
<variablelist>
Format of input. Supported values are
<literal>marc</literal> (for ISO2709), <literal>xml</literal>
(MARCXML/MarcXchange) and <literal>json</literal>
- (<ulink url="&url.marc_in_json;">MARC-in_JSON</ulink>).
+ (<ulink url="&url.marc_in_json;">MARC-in-JSON</ulink>).
</para>
</listitem>
</varlistentry>
<literal>marc</literal> (ISO2709),
<literal>marcxhcange</literal> (for MarcXchange),
or <literal>json</literal>
- (<ulink url="&url.marc_in_json;">MARC-in_JSON </ulink>).
+ (<ulink url="&url.marc_in_json;">MARC-in-JSON </ulink>).
</para>
</listitem>
</varlistentry>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>xslt</literal></term>
+ <term><literal>select</literal></term>
<listitem>
<para>
- The <literal>xslt</literal> element specifies a conversion
- via &acro.xslt;. The following attributes may be specified:
+ The <literal>select</literal> selects one or more text nodes
+ and decodes them as XML.
+ The following attributes may be specified:
<variablelist>
- <varlistentry><term><literal>stylesheet</literal> (REQUIRED)</term>
+ <varlistentry><term><literal>path</literal> (REQUIRED)</term>
<listitem>
<para>
- Stylesheet file.
+ X-Path expression for selecting text nodes.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
+ <para>
+ This conversion is available in YAZ 5.8.0 and later.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><literal>xslt</literal></term>
+ <listitem>
+ <para>
+ The <literal>xslt</literal> element specifies a conversion
+ via &acro.xslt;. The following attributes may be specified:
+ <variablelist>
+ <varlistentry><term><literal>stylesheet</literal> (REQUIRED)</term>
+ <listitem>
+ <para>
+ Stylesheet file.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</para>
</sect2>
<example id="tools.retrieval.marcxml">
<title>MARCXML backend</title>
<para>
- SRW/SRU and Solr backends returns records in XML.
+ SRW/SRU and Solr backends return records in XML.
If they return MARCXML or MarcXchange, the retrieval module
can convert those into ISO2709 formats, most commonly USMARC
(AKA MARC21).
</para>
<para>
In SRU/Solr, however, the model is different. Here, sorting is specified
- during the the search operation. Note, however, that SRU might
+ during the search operation. Note, however, that SRU might
perform sort as separate search, by referring to an existing result-set
in the query (result-set reference).
</para>
<sect2>
<title>Using the Z39.50 sort service</title>
<para>
- yaz-client and the ZOOM API supports the Z39.50 sort facility. In any
+ yaz-client and the ZOOM API support the Z39.50 sort facility. In any
case the sort sequence or sort critiera is using a string notation.
This notation is a one-line notation suitable for being manually
- entered or generated and allows for easy logging (one liner).
+ entered or generated, and allows for easy logging (one liner).
For the ZOOM API, the sort is specified in the call to ZOOM_query_sortby
function. For yaz-client the sort is performed and specified using
the sort and sort+ commands. For description of the sort criteria notation
critieria is specified along with the search query.
</para>
<para>
- The sort is triggered by the presence of type 7 and the value of type 7
+ The sort is triggered by the presence of type 7, and the value of type 7
specifies the
<ulink url="http://www.loc.gov/z3950/agency/asn1.html#SortKeySpec">
sortRelation
- </ulink>
+ </ulink>.
The value for type 7 is 1 for ascending and 2 for descending.
For the
<ulink url="http://www.loc.gov/z3950/agency/asn1.html#SortElement">
only the generic part is handled. If generic sortKey is of type
sortField, then attribute type 1 is present and the value is
sortField (InternationalString). If generic sortKey is of type
- sortAttributes, then the attributes in list is used . generic sortKey
+ sortAttributes, then the attributes in the list are used. Generic sortKey
of type elementSpec is not supported.
</para>
<para>
<sect1 id="facets">
<title>Facets</title>
<para>
- YAZ supports facets for in Solr, SRU 2.0 and Z39.50 protocols.
+ YAZ supports facets in the Solr, SRU 2.0 and Z39.50 protocols.
</para>
<para>
Like Type-1/RPN, YAZ supports a string notation for specifying
<function>yaz_pqf_parse_facet_list</function>.
</para>
<para>
- For ZOOM C the facets are given by option "facets"
- For yaz-client it is used for the facets command.
+ For ZOOM C the facets are given by option "facets".
+ For yaz-client it is used for the 'facets' command.
</para>
<para>
The grammar of this specification is as follows:
</literallayout>
The notation is inspired by PQF. The string following '@attr'
- may not include blanks and is of the form
+ must not include blanks and is of the form
<replaceable>type</replaceable><literal>=</literal><replaceable>value</replaceable>,
where <replaceable>type</replaceable> is an integer and
<replaceable>value</replaceable> is a string or an integer.
<row>
<entry>1</entry>
<entry>
- Field-name. This is often a string, eg "Author", "Year", etc.
+ Field-name. This is often a string, e.g. "Author", "Year", etc.
</entry>
</row>
<row>
<sect1 id="odr.introduction">
<title>Introduction</title>
<para>
- &odr; is the BER-encoding/decoding subsystem of &yaz;. Care as been taken
+ &odr; is the BER-encoding/decoding subsystem of &yaz;. Care has been taken
to isolate &odr; from the rest of the package - specifically from the
transport interface. &odr; may be used in any context where basic
ASN.1/BER representations are used.
releasing little bits of memory. Rather than managing the individual,
small bits of space, the system maintains a free-list of larger chunks
of memory, which are handed out in small bits. This scheme is
- generally known as a <emphasis>nibble memory</emphasis> system.
+ generally known as a <emphasis>nibble-memory</emphasis> system.
It is very useful for maintaining short-lived constructions such
as protocol PDUs.
</para>
odr_setprint(ODR o, FILE *file);
</synopsis>
before encoders or decoders are being invoked.
- It is also possible to direct the output to a buffer (of indeed
+ It is also possible to direct the output to a buffer (or indeed
another file), by using the more generic mechanism:
<synopsis>
void odr_set_stream(ODR o, void *handle,
The <replaceable>stream_close</replaceable> handler is optional and
if NULL for the function is provided, it will not be invoked.
The <replaceable>stream_write</replaceable> takes the ODR handle
- as parameter, the user defined handle, a type
+ as parameter, the user-defined handle, a type
<literal>ODR_OCTETSTRING</literal>, <literal>ODR_VISIBLESTRING</literal>
- which indicates the type of contents is being written.
+ which indicates the type of contents being written.
</para>
<para>
Another utility useful for diagnostics (error handling) or as
</synopsis>
which returns a list of current elements that ODR deals with at the
moment. For the returned array, say <literal>ar</literal>,
- <literal>ar[0]</literal> is the top level element,
+ then <literal>ar[0]</literal> is the top level element,
<literal>ar[n]</literal> is the last. The last element has the
property that <literal>ar[n+1] == NULL</literal>.
</para>
The <literal>buf</literal> field should point to the character array
that holds the octetstring. The <literal>len</literal> field holds the
actual length.
- The character array need not be null terminated.
+ The character array need not be null-terminated.
</para>
<para>
To make things a little easier, an alternative is given for string
- types that are not expected to contain embedded NULL characters (eg.
+ types that are not expected to contain embedded NULL characters (e.g.
VisibleString):
</para>
<synopsis>
int odr_cstring(ODR o, char **p, int optional, const char *name);
</synopsis>
<para>
- Which encoded or decodes between OCTETSTRING representations and
- null-terminates C strings.
+ which encodes or decodes between OCTETSTRING representations and
+ null-terminated C strings.
</para>
<para>
- Functions are provided for the derived string types, eg:
+ Functions are provided for the derived string types, e.g.:
</para>
<synopsis>
int odr_visiblestring(ODR o, char **p, int optional,
</synopsis>
<para>
The opaque type <literal>Odr_bitmask</literal> is only suitable for
- holding relatively brief bit strings, eg. for options fields, etc.
+ holding relatively brief bit strings, e.g. for options fields, etc.
The constant <literal>ODR_BITMASK_SIZE</literal> multiplied by 8
gives the maximum possible number of bits.
</para>
parameter is ignored. On decoding, it returns 1 if the type is found in
the data stream. <literal>size</literal> bytes of memory are allocated,
and <literal>*p</literal> is set to point to this space.
- <function>odr_sequence_end()</function> is called at the end of the
+ The <function>odr_sequence_end()</function> is called at the end of the
complex function. Assume that a type is defined like this:
</para>
<screen>
</synopsis>
<para>
Assume that the IMPLICIT in the type definition above were replaced
- with EXPLICIT (or that the IMPLICIT keyword were simply deleted, which
+ with EXPLICIT (or that the IMPLICIT keyword was simply deleted, which
would be equivalent). The structure definition would look the same,
but the function would look like this:
</para>
Notice that the interface here gets kind of nasty. The reason is
simple: Explicitly tagged, constructed types are fairly rare in
the protocols that we care about, so the
- esthetic annoyance (not to mention the dangers of a cluttered
+ aesthetic annoyance (not to mention the dangers of a cluttered
interface) is less than the time that would be required to develop a
better interface. Nevertheless, it is far from satisfying, and it's a
point that will be worked on in the future. One option for you would
declaring sequence elements (including CHOICEs) optional.
</para>
<para>
- The ASN.1 specifications naturally requires that each member of a
+ The ASN.1 specifications naturally require that each member of a
CHOICE have a distinct tag, so they can be told apart on decoding.
Sometimes it can be useful to define a CHOICE that has multiple types
that share the same tag. You'll need some other mechanism, perhaps
<para>
provides this functionality. When called, it leaves a notice for the next
call to <function>odr_choice()</function> to be called on the decoding
- stream <literal>o</literal> that only the <literal>arm</literal> entry with
+ stream <literal>o</literal>, that only the <literal>arm</literal> entry with
a <literal>which</literal> field equal to <literal>what</literal>
should be tried.
</para>
<para>
The <function>cs_create</function> function returns a null-pointer
if a system error occurs.
- The <literal>blocking</literal> parameter should be one if
- you wish the association to operate in blocking mode, zero otherwise.
+ The <literal>blocking</literal> parameter should be '1' if
+ you wish the association to operate in blocking mode, and '0' otherwise.
The <literal>protocol</literal> field should be
<literal>PROTO_Z3950</literal> or <literal>PROTO_HTTP</literal>.
Protocol <literal>PROTO_SR</literal> is no longer supported.
should call it repeatedly with the same values of <literal>buf</literal>
and <literal>len</literal>, until the buffer has been transmitted.
When a full buffer has been sent, the function will return 0 for
- success. -1 indicates an error condition (see below).
+ success. The return value -1 indicates an error condition (see below).
</para>
<synopsis>
int cs_get(COMSTACK handle, char **buf, int *size);
around internally by the subsystem when partial packages are read. Before
calling
<function>cs_get</function>
- for the fist time, the buffer can be initialized to the null pointer,
- and the length should also be set to 0 - cs_get will perform a
+ for the first time, the buffer can be initialized to the null pointer,
+ and the length should also be set to 0 (cs_get will perform a
<function>malloc(2)</function>
- on the buffer for you. When a full buffer has been read, the size of
- the package is returned (which will always be greater than 1). -1
- indicates an error condition.
+ on the buffer for you). When a full buffer has been read, the size of
+ the package is returned (which will always be greater than 1).
+ The return value -1 indicates an error condition.
</para>
<para>
See also the <function>cs_more()</function> function below.
int cs_fileno(COMSTACK h);
</synopsis>
<para>
- Returns the file descriptor of the association. Use this when
+ returns the file descriptor of the association. Use this when
file-level operations on the endpoint are required
(<function>select(2)</function> operations, specifically).
</para>
<note>
<para>
You may need to use this function with some care if your
- name server service is slow or unreliable
+ name server service is slow or unreliable.
</para>
</note>
</sect1>
<function>cs_straddr</function>. The <parameter>str</parameter>
is similar to that described for <function>cs_straddr</function>
but with a prefix denoting the &comstack; type. Prefixes supported
- are <literal>tcp:</literal>, <literal>unix:</literal> and
- <literal>ssl:</literal> for TCP/IP, UNIX and SSL respectively.
+ are <literal>tcp:</literal> and <literal>unix:</literal> and
+ <literal>ssl:</literal> for TCP/IP and UNIX and SSL respectively.
If no prefix is given, then TCP/IP is used.
The <parameter>blocking</parameter> is passed to
function <function>cs_create</function>. The third parameter
void *cs_get_ssl(COMSTACK cs);
</synopsis>
Returns the SSL handle, <literal>SSL *</literal> for comstack. If comstack
- is not of type SSL, NULL is returned.
+ is not of type SSL, then NULL is returned.
</para>
<para>
<synopsis>
</synopsis>
<para>
You can the textual representation of the error code
- by using <function>cs_errmsg</function> - which
- works like <function>strerror(3)</function>
+ by using <function>cs_errmsg</function>, which
+ works like <function>strerror(3)</function>.
</para>
<synopsis>
const char *cs_errmsg(int n);
</synopsis>
<para>
- It is also possible to get straight to the textual represenataion
- without the error code by using
+ It is also possible to get straight to the textual representation
+ without the error code, by using
<function>cs_strerror</function>.
</para>
<synopsis>