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
Z39.50 types. You'll also find the protocol definitions:
- <filename>z3950v3.asn</filename>, <filename>esupdate.asn</filename>,
+ <filename>z3950v3.asn</filename>, <filename>esupdate.asn</filename>,
and others.
</para>
</sect1>
<sect1 id="asn.preparing"><title>Preparing PDUs</title>
-
+
<para>
A structure representing a complex ASN.1 type doesn't in itself contain the
members of that type. Instead, the structure contains
taste, there are at least three different approaches that you may take
when you allocate the structures.
</para>
-
+
<para>
You can use static or automatic local variables in the function that
prepares the PDU. This is a simple approach, and it provides the most
some of its elements, while you leave other elements pointing to global
or per-session default variables.
</para>
-
+
<para>
The &asn; module provides an important aid in creating new PDUs. For
each of the PDU types (say, <function>Z_InitRequest</function>), a
<synopsis>
Z_<type> *zget_<type>(ODR o);
</synopsis>
-
+
<para>
eg.:
</para>
-
+
<synopsis>
Z_InitRequest *zget_InitRequest(ODR o);
</synopsis>
<function>zget_APDU()</function> is provided, which allocates
a top-level Z-APDU of the type requested:
</para>
-
+
<synopsis>
Z_APDU *zget_APDU(ODR o, int which);
</synopsis>
-
+
<para>
The <varname>which</varname> parameter is (of course) the discriminator
belonging to the <varname>Z_APDU</varname> <literal>CHOICE</literal> type.
All of the interface described here is provided by the &asn; module, and
you access it through the <filename>proto.h</filename> header file.
-
+
</para>
</sect1>
<sect1 id="asn.external"><title>EXTERNAL Data</title>
-
+
<para>
In order to achieve extensibility and adaptability to different
application domains, the new version of the protocol defines many
specialized version of the EXTERNAL construct, called
<literal>Z_External</literal>.It is defined thus:
</para>
-
+
<screen>
typedef struct Z_External
{
} u;
} Z_External;
</screen>
-
+
<para>
When decoding, the &asn; module will attempt to determine which
syntax describes the data by looking at the reference fields
For non-ASN.1 data such as MARC records, use the
<literal>octet_aligned</literal> arm of the union.
</para>
-
+
<para>
Some servers return ASN.1 structured data values (eg. database
records) as BER-encoded records placed in the
these records. To help you decode the records in the application, the
function
</para>
-
+
<screen>
Z_ext_typeent *z_ext_gettypebyref(const oid *oid);
</screen>
<literal>Z_ext_typeent</literal>
is defined as:
</para>
-
+
<screen>
typedef struct Z_ext_typeent
{
Odr_fun fun; /* decoder function */
} Z_ext_typeent;
</screen>
-
+
<para>
The <literal>what</literal> member contains the
<literal>Z_External</literal> union discriminator value for the
record syntax, the value of <literal>fun</literal> would be
<literal>z_SUTRS</literal> (a function pointer).
</para>
-
+
<para>
If you receive an EXTERNAL which contains an octet-string value that
you suspect of being an ASN.1-structured data value, you can use
function to decode the BER string (see <xref linkend="odr.use"/>
).
</para>
-
+
<para>
If you want to <emphasis>send</emphasis> EXTERNALs containing
ASN.1-structured values in the occtet-aligned branch of the CHOICE, this
is necessary to tell the different, structured types apart
on decoding.
</para>
-
+
<note>
<para>
Eventually, the EXTERNAL processing will most likely
various modules.
</para>
</note>
-
+
</sect1>
<sect1 id="asn.pdu"><title>PDU Contents Table</title>
-
+
<para>
We include, for reference, a listing of the fields of each top-level
PDU, as well as their default settings.
</para>
-
+
<table frame="top" id="asn.default.initialize.request">
<title>Default settings for PDU Initialize Request</title>
<tgroup cols="3">
</row>
</thead>
<tbody>
-
+
<row><entry>
referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
</entry></row>
</tbody>
</tgroup>
</table>
-
+
<table frame="top" id="asn.default.present.response">
<title>Default settings for PDU Present Response</title>
<tgroup cols="3">
</tbody>
</tgroup>
</table>
-
+
<table frame="top" id="asn.default.delete.result.set.request">
<title>Default settings for Delete Result Set Request
</title>
</row>
</thead>
<tbody>
-
+
<row><entry>
referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
</entry></row>
</row>
</thead>
<tbody>
-
+
<row><entry>
referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
</entry></row>
<row><entry>
otherInfo</entry><entry>Z_OtherInformation</entry><entry>NULL
</entry></row>
-
+
</tbody>
</tgroup>
</table>
</row>
</thead>
<tbody>
-
+
<row><entry>
referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
</entry></row>
</row>
</thead>
<tbody>
-
+
<row><entry>
referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
</entry></row>
</tbody>
</tgroup>
</table>
-
+
<table frame="top" id="asn.default.access.control.request">
<title>Default settings for Access Control Request</title>
<tgroup cols="3">
</row>
</thead>
<tbody>
-
+
<row><entry>
referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
</entry></row>
</row>
</thead>
<tbody>
-
+
<row><entry>
referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
</entry></row>
</row>
</thead>
<tbody>
-
+
<row><entry>
referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
</entry></row>
<row><entry>
otherInfo</entry><entry>Z_OtherInformation</entry><entry>NULL
</entry></row>
-
+
</tbody>
</tgroup>
</table>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
[
<!ENTITY % local SYSTEM "local.ent">
<productnumber>&version;</productnumber>
<info><orgname>Index Data</orgname></info>
</refentryinfo>
-
+
<refmeta>
<refentrytitle>Bib-1 Attribute Set</refentrytitle>
<manvolnum>7</manvolnum>
<refmiscinfo class="manual">Conventions and miscellaneous</refmiscinfo>
</refmeta>
-
+
<refnamediv>
<refname>bib1-attr</refname>
<refpurpose>Bib-1 Attribute Set</refpurpose>
</refnamediv>
-
+
<refsect1><title>DESCRIPTION</title>
<para>
This reference entry lists the Bib-1 attribute set types and values.
Position (3), Structure (4), Truncation (5) and completeness (6).
</para>
</refsect1>
-
+
<refsect1><title>USE (1)</title>
<para>
<screen>
</screen>
</para>
</refsect1>
-
+
<refsect1><title>RELATION (2)</title>
<para>
<screen>
</screen>
</para>
</refsect1>
-
+
<refsect1><title>POSITION (3)</title>
<para>
<screen>
</screen>
</para>
</refsect1>
-
+
<refsect1><title>STRUCTURE (4)</title>
<para>
<screen>
</screen>
</para>
</refsect1>
-
+
<refsect1><title>COMPLETENSS (6)</title>
<para>
<screen>
</screen>
</para>
</refsect1>
-
+
<refsect1><title>SORTING (7)</title>
<para>
<screen>
embedding a sort critieria into a query.
</para>
</refsect1>
-
+
<refsect1><title>SEE ALSO</title>
<para>
<chapter id="comstack"><title>The COMSTACK Module</title>
-
+
<sect1 id="comstack.synopsis"><title>Synopsis (blocking mode)</title>
-
+
<programlisting><![CDATA[
COMSTACK stack;
char *buf = 0;
perror("cs_create"); /* use perror() here since we have no stack yet */
return -1;
}
-
+
server_address_ip = cs_straddr(stack, server_address_str);
if (!server_address_ip)
{
fprintf(stderr, "cs_straddr: address could not be resolved\n");
return -1;
}
-
+
status = cs_connect(stack, server_address_ip);
if (status != 0) {
fprintf(stderr, "cs_connect: %s\n", cs_strerror(stack));
return -1;
}
-
+
status = cs_put(stack, protocol_package, protocol_package_length);
if (status) {
fprintf(stderr, "cs_put: %s\n", cs_strerror(stack));
return -1;
}
/* Now get a response */
-
+
length_incoming = cs_get(stack, &buf, &size);
if (!length_incoming) {
fprintf(stderr, "Connection closed\n");
fprintf(stderr, "cs_get: %s\n", cs_strerror(stack));
return -1;
}
-
+
/* Print result */
fwrite(buf, length_incoming, 1, stdout);
-
+
/* clean up */
cs_close(stack);
if (buf)
of losing generality, and it may prove that the interface will need
extension later on.
</para>
-
+
<note>
<para>
There hasn't been interest in the XTImOSI stack for some years.
<synopsis>
COMSTACK cs_create(CS_TYPE type, int blocking, int protocol);
</synopsis>
-
+
<para>
Creates an instance of the protocol stack - a communications endpoint.
The <literal>type</literal> parameter determines the mode
of communication. At present the following values are supported:
</para>
-
+
<variablelist>
<varlistentry><term><literal>tcpip_type</literal></term>
<listitem><para>TCP/IP (BER over TCP/IP or HTTP over TCP/IP)
</para></listitem>
</varlistentry>
<varlistentry><term><literal>ssl_type</literal></term>
- <listitem><para>Secure Socket Layer (SSL). This COMSTACK
+ <listitem><para>Secure Socket Layer (SSL). This COMSTACK
is experimental and is not fully implemented. If
HTTP is used, this effectively is HTTPS.
</para></listitem>
</para></listitem>
</varlistentry>
</variablelist>
-
+
<para>
The <function>cs_create</function> function returns a null-pointer
if a system error occurs.
<para>
For UNIX sockets, the format of an address is the socket filename.
</para>
-
+
<para>
When a connection has been established, you can use
</para>
</para>
</sect1>
-
+
<sect1 id="comstack.diagnostics"><title>Diagnostics</title>
<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
+ without the error code by using
<function>cs_strerror</function>.
</para>
-
+
<synopsis>
const char *cs_strerror(COMSTACK h);
</synopsis>
-
+
</sect1>
<sect1 id="comstack.summary"><title>Summary and Synopsis</title>
<synopsis><![CDATA[
#include <yaz/comstack.h>
-
+
#include <yaz/tcpip.h> /* this is for TCP/IP and SSL support */
#include <yaz/unix.h> /* this is for UNIX socket support */
-
+
COMSTACK cs_create(CS_TYPE type, int blocking, int protocol);
-
+
COMSTACK cs_createbysocket(int s, CS_TYPE type, int blocking,
int protocol);
COMSTACK cs_create_host(const char *str, int blocking,
void **vp);
-
+
int cs_bind(COMSTACK handle, int mode);
-
+
int cs_connect(COMSTACK handle, void *address);
-
+
int cs_rcvconnect(COMSTACK handle);
-
+
int cs_listen(COMSTACK handle);
COMSTACK cs_accept(COMSTACK handle);
fixes or suggestions. If we're missing somebody, of if you, for
whatever reason, don't like to be listed here, let us know.
</para>
-
+
<itemizedlist>
<listitem><para>
Gary Anderson
</para></listitem>
</itemizedlist>
</appendix>
-
+
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
<chapter id="future"><title>Future Directions</title>
-
+
<para>
We have a new and better version of the front-end server on the drawing
board. Resources and external commitments will govern when we'll be
flexibility, greater support for access/resource control, and easy
support for Explain (possibly with Zebra as an extra database engine).
</para>
-
+
<para>
&yaz; is a BER toolkit and as such should support all protocols
out there based on that. We'd like to see running ILL applications.
LDAP. Maybe a generic framework for doing IR using both LDAP and
Z39.50 transparently.
</para>
-
+
<para>
The SOAP implementation is incomplete. In the future we hope
to add more features to it. Perhaps make a WSDL/XML Schema compiler.
<para>
It would be neat to have a proper module mechanism for the Generic
- Frontend Server so that backend would be dynamically
+ Frontend Server so that backend would be dynamically
loaded (as shared objects / DLLs).
</para>
</para>
</chapter>
-
+
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
-<!--
+<!--
Options for generic frontend server and yaz-ztest.
Included in both manual and man page for yaz-ztest
-->
<variablelist>
-
+
<varlistentry><term><literal>-a </literal>
<replaceable>file</replaceable></term>
<listitem><para>
The special name <literal>-</literal> (dash) sends output to
<literal>stderr</literal>.
</para></listitem></varlistentry>
-
+
<varlistentry><term><literal>-S</literal></term>
<listitem><para>
Don't fork or make threads on connection requests. This is good for
a software malfunction (okay then, a crash) from affecting all
current users.
</para></listitem></varlistentry>
-
+
<varlistentry><term><literal>-1</literal></term>
<listitem><para>
Like <literal>-S</literal> but after one session the server
exits. This mode is for debugging <emphasis>only</emphasis>.
</para></listitem></varlistentry>
-
+
<varlistentry><term><literal>-T</literal></term>
<listitem><para>
Operate the server in threaded mode. The server creates a thread
<varlistentry><term><literal>-w </literal>
<replaceable>dir</replaceable></term>
<listitem><para>
- The server changes to this directory during before listening
+ The server changes to this directory during before listening
on incoming connections. This option is useful
when the server is operating from the <application>inetd</application>
daemon (see <literal>-i</literal>).
<replaceable>pidfile</replaceable></term>
<listitem><para>
Specifies that the server should write its Process ID to
- file given by <replaceable>pidfile</replaceable>.
+ file given by <replaceable>pidfile</replaceable>.
A typical location would be <filename>/var/run/yaz-ztest.pid</filename>.
</para></listitem></varlistentry>
Use this to make the the server run from the
<application>inetd</application> server (UNIX only).
</para></listitem></varlistentry>
-
+
<varlistentry><term><literal>-D</literal></term>
<listitem><para>
Use this to make the server put itself in the background and
- run as a daemon. If neither <literal>-i</literal> nor
+ run as a daemon. If neither <literal>-i</literal> nor
<literal>-D</literal> is given, the server starts in the foreground.
</para></listitem></varlistentry>
-
+
<varlistentry><term><literal>-install</literal></term>
<listitem><para>
Use this to install the server as an NT service
- (Windows NT/2000/XP only).
+ (Windows NT/2000/XP only).
Control the server by going to the Services in the Control Panel.
</para></listitem></varlistentry>
-
+
<varlistentry><term><literal>-installa</literal></term>
<listitem><para>
Use this to install and activate the server as an NT service
- (Windows NT/2000/XP only).
+ (Windows NT/2000/XP only).
Control the server by going to the Services in the Control Panel.
</para></listitem></varlistentry>
-
+
<varlistentry><term><literal>-remove</literal></term>
<listitem><para>
Use this to remove the server from the NT services
- (Windows NT/2000/XP only).
+ (Windows NT/2000/XP only).
</para></listitem></varlistentry>
-
+
<varlistentry><term><literal>-t </literal>
<replaceable>minutes</replaceable></term>
<listitem><para>
Idle session timeout, in minutes.
</para></listitem></varlistentry>
-
+
<varlistentry><term><literal>-k </literal>
<replaceable>size</replaceable></term>
<listitem><para>
<refentrytitle>hosts_access</refentrytitle>
<manvolnum>5</manvolnum>
</citerefentry>
- and
+ and
<citerefentry>
<refentrytitle>tcpd</refentrytitle>
<manvolnum>8</manvolnum>
the input format to <literal>strftime()</literal>.
</para></listitem>
</varlistentry>
-
+
</variablelist>
<!-- Keep this comment at the end of the file
-<!--
+<!--
cmd description of YAZ GFS application.
Included in both manual and man page for yaz-ztest
-->
-<!--
+<!--
Description of the virtual host mechanism in YAZ GFS
Included in both manual and man page for yaz-ztest
-->
</note>
<para>
The YAZ frontend server uses XML to describe the backend
- configurations. Command-line option <literal>-f</literal>
+ configurations. Command-line option <literal>-f</literal>
specifies filename of the XML configuration.
</para>
<para>
</para>
<para>
The <literal>listen</literal> describes listener (transport end point),
- such as TCP/IP, Unix file socket or SSL server. Content for
+ such as TCP/IP, Unix file socket or SSL server. Content for
a listener:
<variablelist>
<varlistentry><term>CDATA (required)</term>
<listitem>
<para>
The CDATA for the <literal>listen</literal> element holds the
- listener string, such as <literal>tcp:@:210</literal>,
+ listener string, such as <literal>tcp:@:210</literal>,
<literal>tcp:server1:2100</literal>,
etc.
</para>
<para>
Specifies a filename that includes CQL to RPN conversion for this
backend server. See &reference-tools-cql-map;
- If given, the backend server will only "see" a Type-1/RPN query.
+ If given, the backend server will only "see" a Type-1/RPN query.
</para>
</listitem>
</varlistentry>
<para>
Specifies a filename that includes CCL to RPN conversion for this
backend server. See &reference-tools-ccl-qualifiers;
- If given, the backend server will only "see" a Type-1/RPN query.
+ If given, the backend server will only "see" a Type-1/RPN query.
</para>
</listitem>
</varlistentry>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry><term>element <literal>docpath</literal> (optional)</term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry><term>element <literal>explain</literal> (optional)</term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>
-
+
</variablelist>
</para>
-
+
<para>
The XML below configures a server that accepts connections from
two ports, TCP/IP port 9900 and a local UNIX file socket.
<chapter id="installation"><title>Compilation and Installation</title>
-
+
<sect1 id="installation-introduction"><title>Introduction</title>
<para>
The latest version of the software will generally be found at:
<para>
We have tried our best to keep the software portable, and on many
platforms, you should be able to compile everything with little or
- no changes.
+ no changes.
</para>
<para>
<ulink url="&url.solaris;">SunOS 5.10 (sparc)</ulink>,
Windows 7, Windows Xp.
</para>
-
+
<para>
Some versions have be known to work on HP/UX,
DEC Unix, <ulink url="&url.netbsd;">NetBSD</ulink>,
<literal>#ifdefs</literal> for individual platforms, and we'd
like to keep it that way as far as it makes sense.
</para>
-
+
<para>
We maintain a mailing-list for the purpose of announcing new releases and
- bug-fixes, as well as general discussion. Subscribe by
+ bug-fixes, as well as general discussion. Subscribe by
filling-in the form
<ulink url="&url.yaz.mailinglist;">here</ulink>.
- General questions and problems can be directed at
+ General questions and problems can be directed at
<ulink url="&url.yaz.mail;"/>, or the address given at the top of
this document.
</para>
-
+
</sect1>
<sect1 id="installation.unix"><title>UNIX</title>
<para>
- We provide
+ We provide
<ulink url="&url.debian;">Debian GNU/Linux</ulink> (i386 and amd64),
<ulink url="&url.ubuntu;">Ubuntu</ulink> (i386 and amd64)
- and
- <ulink url="&url.centos;">CentOS</ulink> (amd64 only) packages for &yaz;.
+ and
+ <ulink url="&url.centos;">CentOS</ulink> (amd64 only) packages for &yaz;.
You should be able to create packages for other CPUs by building
them from the source package.
</para>
-
+
<para>
YAZ is also part of several packages repositories. Some of them are
- </para>
+ </para>
<itemizedlist>
<listitem>
</para>
</listitem>
</itemizedlist>
-
+
<sect2 id="installation.source.unix">
<title>Compiling from source on Unix</title>
-
+
<para>
Note that if your system doesn't have a native ANSI C compiler, you may
have to acquire one separately. We recommend
If you wish to use character set conversion facilities in &yaz; or if you
are compiling &yaz; for use with Zebra it is a good idea to ensure that
the iconv library is installed. Some Unixes today already have it
- - if not, we suggest
+ - if not, we suggest
<ulink url="&url.libiconv;">GNU libiconv</ulink>.
</para>
<para>
- YAZ 3.0.16 and later includes a wrapper for the
- <ulink url="&url.icu;">ICU</ulink>
+ YAZ 3.0.16 and later includes a wrapper for the
+ <ulink url="&url.icu;">ICU</ulink>
(International Components for Unicode).
In order to use this, the developer version of the ICU library
must be available.
GNU <ulink url="&url.bison;">Bison</ulink>.
This tool is only needed if you're using the CVS 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 CVS
version of &yaz; or you're using the compiler to built own codecs
- for private ASN.1.
+ for private ASN.1.
</para>
-
+
<para>
Generally it should be sufficient to run configure without options,
like this:
</para>
-
+
<screen>
./configure
</screen>
-
+
<para>
The configure script attempts to use use the C compiler specified by
the <literal>CC</literal> environment variable. If not set, GNU C will be
Bourne-compatible shell you may pass something like this to use a
particular C compiler with optimization enabled:
</para>
-
+
<screen>
CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
</screen>
-
+
<para>
To customize &yaz;, the configure script also accepts a set of options.
The most important are:
-
+
<variablelist>
<varlistentry><term>
<literal>--prefix</literal>=<replaceable>prefix</replaceable></term>
<refentrytitle>hosts_access</refentrytitle>
<manvolnum>5</manvolnum>
</citerefentry>
- and
+ and
<citerefentry>
<refentrytitle>tcpd</refentrytitle>
<manvolnum>8</manvolnum>
equivalent to <literal>--enable-static</literal>.
</para></listitem>
</varlistentry>
-
+
<varlistentry><term>
<literal>--with-iconv</literal>[=<replaceable>prefix</replaceable>]
</term>
<listitem><para>Compile &yaz; with iconv library in directory
<replaceable>prefix</replaceable>. By default configure will
search for iconv on the system. Use this option if it
- doesn't find iconv. Alternatively,
+ doesn't find iconv. Alternatively,
<literal>--without-iconv</literal>, can be uset to force &yaz;
not to use iconv.
</para></listitem>
<varlistentry><term>
<literal>--with-xslt</literal>[=<replaceable>prefix</replaceable>]
</term>
- <listitem><para>Compile &yaz; with
+ <listitem><para>Compile &yaz; with
<ulink url="&url.libxslt;">libxslt</ulink> in directory
- <replaceable>prefix</replaceable>.
+ <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
- libxslt is not found automatically. Alternatively,
+ libxslt is not found automatically. Alternatively,
<literal>--without-xslt</literal>, can be used to force &yaz;
not to use libxslt.
</para>
<varlistentry><term>
<literal>--with-xml2</literal>[=<replaceable>prefix</replaceable>]
</term>
- <listitem><para>Compile &yaz; with
+ <listitem><para>Compile &yaz; with
<ulink url="&url.libxml2;">libxml2</ulink> in directory
- <replaceable>prefix</replaceable>.
+ <replaceable>prefix</replaceable>.
Use this option if you want &yaz; to use XML and support SRU.
By default, configure will
search for libxml2 on the system. Use this option if it
- libxml2 is not found automatically. Alternatively,
+ libxml2 is not found automatically. Alternatively,
<literal>--without-xml2</literal>, can be used to force &yaz;
not to use libxml2.
</para>
<varlistentry><term>
<literal>--with-icu</literal>[=<replaceable>prefix</replaceable>]
</term>
- <listitem><para>&yaz; will be linked the
+ <listitem><para>&yaz; will be linked the
<ulink url="&url.icu;">ICU</ulink> library in the prefix if given.
If prefix is not given, the libraries exposed by the script
<application>icu-config</application> will be used if found.
</varlistentry>
</variablelist>
-
+
</para>
<para>
When configured, build the software by typing:
make
</screen>
</para>
-
+
<para>
The following files are generated by the make process:
<variablelist>
<listitem><para>
Main &yaz; library. This is no ordinary library. It's
a Libtool archive.
- By default, &yaz; creates a static library in
+ By default, &yaz; creates a static library in
<filename>lib/.libs/libyaz.a</filename>.
</para></listitem>
</varlistentry>
-
+
<varlistentry><term><filename>src/libyaz_server.la</filename></term>
<listitem><para>
Generic Frontend server. This is an add-on for libyaz.la.
threads are available on the platform.
</para></listitem>
</varlistentry>
-
+
<varlistentry><term><filename>src/libyaz_icu.la</filename></term>
<listitem><para>
Functions that wrap the ICU library.
</para></listitem>
</varlistentry>
-
+
<varlistentry><term><filename>ztest/yaz-ztest</filename></term>
- <listitem><para>Test Z39.50 server.
+ <listitem><para>Test Z39.50 server.
</para></listitem>
</varlistentry>
-
+
<varlistentry><term><filename>client/yaz-client</filename></term>
<listitem><para>Z39.50 client for testing the protocol.
See chapter <link linkend="yaz-client">
&yaz;.
</para></listitem>
</varlistentry>
-
+
<varlistentry><term><filename>util/yaz-asncomp</filename></term>
<listitem><para>The ASN.1 compiler for &yaz;. Requires the
Tcl Shell, <application>tclsh</application>, in
<literal>PATH</literal> to operate.
</para></listitem>
</varlistentry>
-
+
<varlistentry><term><filename>util/yaz-iconv</filename></term>
<listitem><para>This program converts data in one character set to
another. This command exercises the YAZ character set
conversion API.
</para></listitem>
</varlistentry>
-
+
<varlistentry><term><filename>util/yaz-marcdump</filename></term>
<listitem><para>This program parses ISO2709 encoded MARC records
and prints them in line-format or XML.
</para></listitem>
</varlistentry>
-
+
<varlistentry><term><filename>util/yaz-icu</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
useful.
</para></listitem>
</varlistentry>
-
+
<varlistentry><term><filename>zoom/zoomsh</filename></term>
<listitem><para>
- A simple shell implemented on top of the
+ A simple shell implemented on top of the
<link linkend="zoom">ZOOM</link> functions.
The shell is a command line application that allows you to enter
simple commands to perform ZOOM operations.
</para></listitem>
</varlistentry>
-
- <varlistentry><term><filename>zoom/zoomtst1</filename>,
+
+ <varlistentry><term><filename>zoom/zoomtst1</filename>,
<filename>zoom/zoomtst2</filename>, ..</term>
<listitem><para>
Several small applications that demonstrates the ZOOM API.
</para></listitem>
</varlistentry>
</variablelist>
-
+
</para>
-
+
<para>
- If you wish to install &yaz; in system directories
+ If you wish to install &yaz; in system directories
<filename>/usr/local/bin</filename>,
<filename>/usr/local/lib</filename> .. etc, you can type:
</para>
-
+
<screen>
make install
</screen>
-
+
<para>
You probably need to have root access in order to perform this.
You must specify the <literal>--prefix</literal> option for configure if
- you wish to install &yaz; in other directories than the default
+ you wish to install &yaz; in other directories than the default
<filename>/usr/local/</filename>.
</para>
-
+
<para>
If you wish to perform an un-installation of &yaz;, use:
</para>
-
+
<screen>
make uninstall
</screen>
-
+
<para>
This will only work if you haven't reconfigured &yaz; (and therefore
changed installation prefix). Note that uninstall will not
<screen>
#include <proto.h>
</screen>
- </para>
+ </para>
<para>
For Libtool users, the <filename>yaz-config</filename> script provides
a different variant of option <literal>--libs</literal>, called
</sect2>
</sect1>
<sect1 id="installation.win32"><title>WIN32</title>
-
+
<para>The easiest way to install YAZ on Windows is by downloading
- an installer from
+ an installer from
<ulink url="&url.yaz.download.win32;">here</ulink>.
The installer comes with source too - in case you wish to
- compile YAZ with different Compiler options etc.
+ compile YAZ with different Compiler options etc.
</para>
-
+
<sect2 id="installation.win32.source">
<title>Compiling from Source on WIN32</title>
<para>
<filename>WIN</filename> where the file <filename>makefile</filename>
is located. Customize the installation by editing the
<filename>makefile</filename> file (for example by using notepad).
-
+
The following summarizes the most important settings in that file:
-
+
<variablelist>
<varlistentry><term><literal>DEBUG</literal></term>
<listitem><para>
(<filename>cql.y</filename>).
</para>
<para>
- A Windows version of GNU Bison is part of
+ A Windows version of GNU Bison is part of
<ulink url="&url.unxutils;">unxutils</ulink>.
</para></listitem>
</varlistentry>
<literal>ICONV_DIR</literal></term>
<listitem><para>
If <literal>HAVE_ICONV</literal> is set to 1, YAZ is compiled
- with iconv support. In this configuration, set
+ with iconv support. In this configuration, set
<literal>ICONV_DIR</literal> to the iconv source directory.
</para></listitem>
</varlistentry>
-
+
<varlistentry>
<term><literal>HAVE_LIBXML2</literal>,
<literal>LIBXML2_DIR</literal></term>
<listitem>
<para>
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
+ 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.
<listitem>
<para>
If <literal>HAVE_LIBXSLT</literal> is set to 1, YAZ is compiled
- with XSLT support. In this configuration, set
- <literal>LIBXSLT_DIR</literal> to the
+ with XSLT support. In this configuration, set
+ <literal>LIBXSLT_DIR</literal> to the
<ulink url="&url.libxslt;">libxslt</ulink> source directory.
</para>
<para>
If <literal>HAVE_ICU</literal> is set to 1, YAZ is compiled
with <ulink url="&url.icu;">ICU</ulink> support.
- In this configuration, set
- <literal>ICU_DIR</literal> to the
+ In this configuration, set
+ <literal>ICU_DIR</literal> to the
<ulink url="&url.icu;">ICU</ulink> source directory.
</para>
</listitem>
</para>
<para>
The following files are generated upon successful compilation:
-
+
<variablelist>
- <varlistentry><term><filename>bin/yaz4.dll</filename> /
+ <varlistentry><term><filename>bin/yaz4.dll</filename> /
<filename>bin/yaz4d.dll</filename></term>
<listitem><para>
&yaz; Release/Debug DLL.
</para></listitem></varlistentry>
-
- <varlistentry><term><filename>lib/yaz4.lib</filename> /
+
+ <varlistentry><term><filename>lib/yaz4.lib</filename> /
<filename>lib/yaz4d.lib</filename></term>
<listitem><para>
Import library for <filename>yaz4.dll</filename> /
<filename>yaz4d.dll</filename>.
</para></listitem></varlistentry>
-
- <varlistentry><term><filename>bin/yaz_cond4.dll</filename> /
+
+ <varlistentry><term><filename>bin/yaz_cond4.dll</filename> /
<filename>bin/yaz_cond4d.dll</filename></term>
<listitem><para>
Release/Debug DLL for condition variable utilities (condvar.c).
</para></listitem></varlistentry>
-
- <varlistentry><term><filename>lib/yaz_cond4.lib</filename> /
+
+ <varlistentry><term><filename>lib/yaz_cond4.lib</filename> /
<filename>lib/yaz_cond4d.lib</filename></term>
<listitem><para>
Import library for <filename>yaz_cond4.dll</filename> /
<filename>yaz_cond4d.dll</filename>.
</para></listitem></varlistentry>
-
+
<varlistentry><term><filename>bin/yaz_icu4.dll</filename> /
<filename>bin/yaz_icu4d.dll</filename></term>
<listitem><para>
Release/Debug DLL for the ICU wrapper utility.
Only build if HAVE_ICU is 1.
</para></listitem></varlistentry>
-
+
<varlistentry><term><filename>lib/yaz_icu4.lib</filename> /
<filename>lib/yaz_icu4d.lib</filename></term>
<listitem><para>
Import library for <filename>yaz_icu4.dll</filename> /
<filename>yaz_icu4d.dll</filename>.
</para></listitem></varlistentry>
-
+
<varlistentry><term><filename>bin/yaz-ztest.exe</filename></term>
<listitem><para>
Z39.50 multi-threaded test/example server. It's a WIN32
console application.
</para></listitem></varlistentry>
-
+
<varlistentry><term><filename>bin/yaz-client.exe</filename></term>
<listitem><para>
&yaz; Z39.50 client application. It's a WIN32 console application.
See chapter <link linkend="yaz-client">YAZ client</link> for more
information.
</para></listitem></varlistentry>
-
+
<varlistentry><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
The application is a command line shell that allows you to enter
simple commands to perform ZOOM operations.
</para></listitem></varlistentry>
-
- <varlistentry><term><filename>bin/zoomtst1.exe</filename>,
+
+ <varlistentry><term><filename>bin/zoomtst1.exe</filename>,
<filename>bin/zoomtst2.exe</filename>, ..</term>
<listitem><para>
Several small applications that demonstrates the ZOOM API.
</para></listitem></varlistentry>
-
+
</variablelist>
-
+
</para>
</sect2>
</para></listitem></varlistentry>
<varlistentry><term>import library <filename>yaz4.lib</filename>
</term><listitem><para>
- You must link with this library. It's located in the
+ You must link with this library. It's located in the
sub directory <filename>lib</filename> of &yaz;.
If you want to link with the debug version of &yaz;, you must
link against <filename>yaz4d.lib</filename> instead.
</sect2>
</sect1>
</chapter>
-
+
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-namecase-general:t
End:
-->
-
+
&yaz; is a C/C++ library for information retrieval applications
using the Z39.50/SRU/SOLR protocols for information retrieval.
</para>
-
+
<para>
Properties of &yaz;:
<itemizedlist>
<listitem><para>
- Complete
+ Complete
<ulink url="&url.z39.50;">Z39.50</ulink> version 3 support.
Amendments and Z39.50-2002 revision is supported.
</para></listitem>
<listitem><para>
- Supports
+ Supports
<ulink url="&url.sru;">SRU GET/POST/SOAP</ulink>
version 1.2 (over HTTP and HTTPS).
</para></listitem>
<listitem><para>
- Includes BER encoders/decoders for the
+ Includes BER encoders/decoders for the
<ulink url="&url.ill;">ISO ILL</ulink>
protocol.
</para></listitem>
<listitem><para>
- Supports
+ Supports
<ulink url="&url.solr;">SOLR</ulink> Web Service version 1.4.x (client side only)
</para></listitem>
<listitem><para>
Supports the following transports: BER over TCP/IP
(<ulink url="&url.ber.over.tcpip;">RFC1729</ulink>),
- BER over unix local socket, and
+ BER over unix local socket, and
<ulink url="&url.http.1.1;">HTTP 1.1</ulink>.
</para></listitem>
<listitem><para>
"Secure BER" (for Z39.50).
</para></listitem>
<listitem><para>
- Offers
+ Offers
<ulink url="&url.zoom;">ZOOM</ulink> C API implementing
Z39.50, SRU and SOLR Web Service.
</para></listitem>
<listitem><para>
The &yaz; library offers a set of useful utilities
related to the protocols, such as MARC (ISO2709) parser,
- CCL (ISO8777) parser,
+ CCL (ISO8777) parser,
<ulink url="&url.cql;">CQL</ulink>
parser, memory management routines, character set conversion.
</para></listitem>
<itemizedlist>
<listitem>
<para>
- <xref linkend="installation"/> contains installation
+ <xref linkend="installation"/> contains installation
instructions for &yaz;. You don't need reading this
if you expect to download &yaz; binaries.
However, the chapter contains information about how
client.
</para>
</listitem>
-
+
<listitem>
<para>
<xref linkend="server"/> describes the generic frontend server
<listitem>
<para>
- <xref linkend="soap"/> describes how SRU and SOAP is used
+ <xref linkend="soap"/> describes how SRU and SOAP is used
in &yaz;. Only if you're developing SRU applications
this section is a must.
</para>
</itemizedlist>
</sect1>
<sect1 id="introduction.api"><title>The API</title>
-
+
<para>
The <ulink url="&url.yaz;">&yaz;</ulink>
toolkit offers several different levels of access to the
If you're developing a client application you should consider the
<link linkend="zoom">ZOOM</link> API.
It is, by far, the easiest way to develop clients in C.
- Server implementers should consider the
+ Server implementers should consider the
<link linkend="server">generic frontend server</link>.
None of those high-level APIs support the whole protocol, but
they do include most facilities used in existing Z39.50 applications.
</listitem>
<listitem>
<para>
- The second layer provides a C represenation of the
+ The second layer provides a C represenation of the
protocol units (packages) for Z39.50 ASN.1, ILL ASN.1,
SRU.
</para>
The &asn; library also provides functions (which are, in turn,
defined using &odr; primitives) for encoding and decoding data values.
Their general form is
-
+
<funcsynopsis>
<funcprototype><funcdef>int <function>z_<replaceable>xxx</replaceable></function></funcdef>
<paramdef>ODR <parameter>o</parameter></paramdef>
</funcsynopsis>
(note the lower-case "z" in the function name)
</para>
-
+
<note>
<para>
If you are using the premade definitions of the &asn; module, and you
<xref linkend="odr.use"/>.
</para>
</note>
-
+
<para>
When you have created a BER-encoded buffer, you can use the &comstack;
subsystem to transmit (or receive) data over the network. The &comstack;
</para>
</listitem>
</itemizedlist>
-
+
<para>
THIS SOFTWARE IS PROVIDED BY INDEX DATA ``AS IS'' AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
<chapter id="odr"><title>The ODR Module</title>
-
+
<sect1 id="odr.introduction"><title>Introduction</title>
<para>
data you wish to decode (eg, <function>odr_integer()</function> odr
<function>z_APDU()</function>).
</para>
-
+
<example id="example.odr.encoding.and.decoding.functions">
<title>Encoding and decoding functions</title>
<synopsis>
int odr_integer(ODR o, Odr_int **p, int optional, const char *name);
-
+
int z_APDU(ODR o, Z_APDU **p, int optional, const char *name);
</synopsis>
</example>
<function>free(2)</function> to release the memory.
You can decode several data elements (by repeated calls to
<function>odr_setbuf()</function> and your decoding function), and
- new memory will be allocated each time. When you do call
+ new memory will be allocated each time. When you do call
<function>odr_reset()</function>, everything decoded since the
last call to <function>odr_reset()</function> will be released.
</para>
Odr_int *valp, *resvalp;
char *bufferp;
int len;
-
+
/* allocate streams */
if (!(encode = odr_createmem(ODR_ENCODE)))
return;
program, so the overhead is quite manageable.
</para>
</example>
-
+
</sect2>
<sect2 id="odr.printing"><title>Printing</title>
Here the user provides an opaque handle and two handlers,
<replaceable>stream_write</replaceable> for writing,
and <replaceable>stream_close</replaceable> which is supposed
- to close/free resources associated with handle.
+ to close/free resources associated with 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.
</para>
<synopsis>
const char **odr_get_element_path(ODR o);
</synopsis>
- which returns a list of current elements that ODR deals with at the
- moment. For the returned array, say <literal>ar</literal>,
+ 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,
<literal>ar[n]</literal> is the last. The last element has the
property that <literal>ar[n+1] == NULL</literal>.
<para>
For a database record part of a PresentResponse the
array returned by <function>odr_get_element</function>
- is <literal>presentResponse</literal>, <literal>databaseOrSurDiagnostics</literal>, <literal>?</literal>, <literal>record</literal>, <literal>?</literal>, <literal>databaseRecord</literal> . The question mark appears due to
+ is <literal>presentResponse</literal>, <literal>databaseOrSurDiagnostics</literal>, <literal>?</literal>, <literal>record</literal>, <literal>?</literal>, <literal>databaseRecord</literal> . The question mark appears due to
unnamed constructions.
</para>
</example>
<para>
There is an ASN.1 tutorial available at
<ulink url="&url.asn.1.tutorial;">this site</ulink>.
- This site also has standards for ASN.1 (X.680) and BER (X.690)
+ This site also has standards for ASN.1 (X.680) and BER (X.690)
<ulink url="&url.asn.1.standards;">online</ulink>.
</para>
</tip>
-
+
<para>
The ODR interface is based loosely on that of the Sun Microsystems
XDR routines.
definition for a type once - and you have the functionality of encoding,
decoding (and pretty-printing) all in one unit.
The resulting C source code is quite compact, and is a pretty
- straightforward representation of the source ASN.1 specification.
+ straightforward representation of the source ASN.1 specification.
</para>
-
+
<para>
In many cases, the model of the XDR functions works quite well in this
role.
<para>
The <literal>Odr_int</literal> is just a simple integer.
</para>
-
+
<para>
This form is typical of the primitive &odr; functions. They are named
after the type of data that they encode or decode. They take an &odr;
<para>
The simplest way of tagging a type is to use the
- <function>odr_implicit_tag()</function> or
+ <function>odr_implicit_tag()</function> or
<function>odr_explicit_tag()</function> macros:
</para>
Odr_int *intval;
Odr_bool *boolval;
} MySequence;
-
+
int mySequence(ODR o, MySequence **p, int optional, const char *name)
{
if (odr_sequence_begin(o, p, sizeof(**p), name) == 0)
<chapter id="server"><title>Generic server</title>
<sect1 id="server.introduction"><title>Introduction</title>
-
+
<para>
If you aren't into documentation, a good way to learn how the
back end interface works is to look at the <filename>backend.h</filename>
</para>
</note>
</sect1>
-
+
<sect1 id="server.frontend"><title>The Database Frontend</title>
<para>
<listitem><para>
Extended Services (optional).
</para></listitem>
-
+
<listitem><para>
Result-Set Delete (optional).
</para></listitem>
<listitem><para>
Result-Set Sort (optional).
</para></listitem>
-
+
<listitem><para>
Return Explain for SRU (optional).
</para></listitem>
-
+
</itemizedlist>
<para>
connection.
If you do use global variables and forking, you should be aware, then,
that these cannot be shared between associations, unless you explicitly
- disable forking by command line parameters.
+ disable forking by command line parameters.
</para>
-
+
<para>
The server provides a mechanism for controlling some of its behavior
without using command-line options. The function
will return a pointer to a <literal>struct statserv_options_block</literal>
describing the current default settings of the server. The structure
contains these elements:
-
+
<variablelist>
<varlistentry><term>
<literal>int dynamic</literal></term><listitem><para>
TRUE. This flag is only read by UNIX-based servers (WIN32 based servers
doesn't fork).
</para></listitem></varlistentry>
-
+
<varlistentry><term>
<literal>int threads</literal></term><listitem><para>
A boolean value, which determines whether the server
that offer POSIX Threads support.
WIN32-based servers always operate in threaded mode.
</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.
</para></listitem></varlistentry>
-
+
<varlistentry><term>
<literal>char logfile[ODR_MAXNAME+1]</literal></term>
<listitem><para>File for diagnostic output ("": stderr).
</para></listitem></varlistentry>
-
+
<varlistentry><term>
<literal>char apdufile[ODR_MAXNAME+1]</literal></term>
<listitem><para>
<literal>PROTO_SR</literal>.
Default is <literal>PROTO_Z39_50</literal>.
</para></listitem></varlistentry>
-
+
<varlistentry><term>
<literal>int idle_timeout;</literal></term>
<listitem><para>Maximum session idle-time, in minutes. Zero indicates
no (infinite) timeout. Default is 15 minutes.
</para></listitem></varlistentry>
-
+
<varlistentry><term>
<literal>int maxrecordsize;</literal></term>
<listitem><para>Maximum permissible record (message) size. Default
<listitem><para>Set user id to the user specified, after binding
the listener addresses.
</para></listitem></varlistentry>
-
+
<varlistentry><term>
<literal>void (*bend_start)(struct statserv_options_block *p)</literal>
</term>
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
- whenever the service is started.
+ whenever the service is started.
</para></listitem></varlistentry>
-
+
<varlistentry><term>
<literal>void (*bend_stop)(struct statserv_options_block *p)</literal>
</term>
a static area. You are allowed to change the contents of the structure,
but the changes will not take effect before you call
</para>
-
+
<synopsis>
void statserv_setcontrol(statserv_options_block *block);
</synopsis>
typedef struct bend_initrequest
{
/** \brief user/name/password to be read */
- Z_IdAuthentication *auth;
+ Z_IdAuthentication *auth;
/** \brief encoding stream (for results) */
ODR stream;
/** \brief printing stream */
ODR print;
/** \brief decoding stream (use stream for results) */
- ODR decode;
+ ODR decode;
/** \brief reference ID */
Z_ReferenceId *referenceId;
/** \brief peer address of client */
- char *peer_name;
-
- /** \brief character set and language negotiation
+ char *peer_name;
+
+ /** \brief character set and language negotiation
- see include/yaz/z-charneg.h
+ see include/yaz/z-charneg.h
*/
Z_CharSetandLanguageNegotiation *charneg_request;
/** \brief character negotiation response */
Z_External *charneg_response;
- /** \brief character set (encoding) for query terms
-
+ /** \brief character set (encoding) for query terms
+
This is NULL by default. It should be set to the native character
set that the backend assumes for query terms */
- char *query_charset;
+ char *query_charset;
+
+ /** \brief whehter query_charset also applies to recors
- /** \brief whehter query_charset also applies to recors
-
Is 0 (No) by default. Set to 1 (yes) if records is in the same
character set as queries. If in doubt, use 0 (No).
*/
<para>
The <literal>auth</literal> member holds the authentication information
part of the Z39.50 Initialize Request. Interpret this if your serves
- requires authentication.
+ requires authentication.
</para>
<para>
For SRU operation, a Bib-1 diagnostic code is mapped to
SRU diagnostic.
</para>
-
+
<synopsis>
int (*bend_fetch) (void *handle, bend_fetch_rr *rr);
<para>
Note that this is handler serves as a supplement for
<function>bend_fetch</function> and need not to be defined in order to
- support search - and retrieve.
+ support search - and retrieve.
</para>
</sect2>
int delete_status; /* status for the whole operation */
int *statuses; /* status each set - indexed as setnames */
ODR stream;
- ODR print;
+ ODR print;
} bend_delete_rr;
</synopsis>
} bend_scan_rr;
</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
+ 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
<literal>scanClause</literal>.
</para>
<note>
</para>
&gfs-synopsis;
-
+
<para>
The options are:
&gfs-options;
</para>
-
+
<para>
A listener specification consists of a transport mode followed by a
colon (:) followed by a listener address. The transport mode is
either <literal>tcp</literal>, <literal>unix:</literal> or
<literal>ssl</literal>.
</para>
-
+
<para>
For TCP and SSL, an address has the form
</para>
<synopsis>
hostname | IP-number [: portnumber]
</synopsis>
-
+
<para>
The port number defaults to 210 (standard Z39.50 port).
</para>
<para>
For TCP/IP and SSL, the special hostnames <literal>@</literal> and
- <literal>@6</literal> are mapped to the addresses
+ <literal>@6</literal> are mapped to the addresses
<literal>INADDR_ANY</literal> (IPV4) and
<literal>IN6ADDR_ANY_INIT</literal> (IPV6)
- respectively.
+ respectively.
</para>
<example id="server.example.running.unix"><title>Running the GFS on Unix</title>
as your public web server and want to offer HTTP port 80
access to the YAZ server on 210, you can use the
<ulink url="&url.apache.directive.proxypass;">
- <literal>ProxyPass</literal></ulink>
+ <literal>ProxyPass</literal></ulink>
directive.
If you have virtual host
<literal>srw.mydomain</literal> you can use the following directives
&gfs-virtual;
</sect1>
</chapter>
-
+
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
<chapter id="soap"><title>SOAP and SRU</title>
<sect1 id="soap.introduction"><title>Introduction</title>
<para>
- &yaz; uses a very simple implementation of
+ &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.
- The implementation uses the
+ The implementation uses the
<ulink url="&url.libxml2.api.tree;">tree API</ulink> of
libxml2 to encode and decode SOAP packages.
</para>
void *client_data, const char *ns);
</synopsis>
Here, <literal>Z_SRW_GDU</literal> is either
- searchRetrieveRequest or a searchRetrieveResponse.
+ searchRetrieveRequest or a searchRetrieveResponse.
</para>
<note>
<para>
int * numberOfRecords;
char * resultSetId;
int * resultSetIdleTime;
-
+
Z_SRW_record *records;
int num_records;
<chapter id="tools"><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
</para>
</note>
<para>
- The PQF is defined by the pquery module in the YAZ library.
+ The PQF is defined by the pquery module in the YAZ library.
There are two sets of function 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
a Z39.50 RPN Query is returned which is created using ODR stream
<literal>o</literal>. If parsing failed, a NULL pointer is
returned.
- Function <function>yaz_pqf_scan</function> takes a scan query in
+ Function <function>yaz_pqf_scan</function> takes a scan query in
<literal>qbuf</literal>. If parsing was successful, the function
returns attributes plus term pointer and modifies
<literal>attributeSetId</literal> to hold attribute set for the
<para>
If the parse went well, <function>p_query_rpn()</function> returns a
pointer to a <literal>Z_RPNQuery</literal> structure which can be
- placed directly into a <literal>Z_SearchRequest</literal>.
+ placed directly into a <literal>Z_SearchRequest</literal>.
If parsing failed, due to syntax error, a NULL pointer is returned.
</para>
<para>
</para>
<para>
- The @attr operator is followed by an attribute specification
+ The @attr operator is followed by an attribute specification
(<literal>attr-spec</literal> above). The specification consists
of an optional attribute set, an attribute type-value pair and
a sub-query. The attribute type-value pair is packed in one string:
is used. This is the only encoding allowed in both versions 2 and 3
of the Z39.50 standard.
</para>
-
+
<sect3 id="PQF-prox">
<title>Using Proximity Operators with PQF</title>
<note>
<para>
The proximity operator <literal>@prox</literal> is a special
and more restrictive version of the conjunction operator
- <literal>@and</literal>. Its semantics are described in
+ <literal>@and</literal>. Its semantics are described in
section 3.7.2 (Proximity) of Z39.50 the standard itself, which
can be read on-line at
<ulink url="&url.z39.50.proximity;"/>
<para>
<screen>
@or @and bob dylan @set Result-1
-
+
@attr 4=1 @and @attr 1=1 "bob dylan" @attr 1=4 "slow train coming"
-
+
@and @attr 2=4 @attr gils 1=2038 -114 @attr 2=2 @attr gils 1=2039 -109
</screen>
<note>
-- Proximity operator
</screen>
-
+
<example id="example.ccl.queries">
<title>CCL queries</title>
<para>
The following queries are all valid:
</para>
-
+
<screen>
dylan
-
+
"bob dylan"
-
+
dylan or zimmerman
-
+
set=1
-
+
(dylan and bob) or set=1
-
+
</screen>
<para>
Assuming that the qualifiers <literal>ti</literal>,
<literal>au</literal>
and <literal>date</literal> are defined we may use:
</para>
-
+
<screen>
ti=self portrait
-
+
au=(bob dylan and slow train coming)
date>1980 and (ti=((self portrait)))
-
+
</screen>
</example>
-
+
</sect3>
<sect3 id="ccl.qualifiers">
<title>CCL Qualifiers</title>
-
+
<para>
Qualifiers are used to direct the search to a particular searchable
index, such as title (ti) and author indexes (au). The CCL standard
<para>
A qualifier specification is of the form:
</para>
-
+
<para>
- <replaceable>qualifier-name</replaceable>
+ <replaceable>qualifier-name</replaceable>
[<replaceable>attributeset</replaceable><literal>,</literal>]<replaceable>type</replaceable><literal>=</literal><replaceable>val</replaceable>
- [<replaceable>attributeset</replaceable><literal>,</literal>]<replaceable>type</replaceable><literal>=</literal><replaceable>val</replaceable> ...
+ [<replaceable>attributeset</replaceable><literal>,</literal>]<replaceable>type</replaceable><literal>=</literal><replaceable>val</replaceable> ...
</para>
-
+
<para>
where <replaceable>qualifier-name</replaceable> is the name of the
qualifier to be used (eg. <literal>ti</literal>),
<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:
- <literal>u</literal> for use,
+ <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
or <literal>c</literal> for completeness.
<ulink url="&url.z39.50.attset.bib1;">list of Bib-1 attributes</ulink>
</para>
<para>
- It is also possible to specify non-numeric attribute values,
+ It is also possible to specify non-numeric attribute values,
which are used in combination with certain types.
The special combinations are:
-
+
<table id="ccl.special.attribute.combos">
<title>Special attribute combos</title>
<tgroup cols="2">
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).
This does not set the structure at all.
</entry>
</row>
-
+
<row><entry><literal>s=ag</literal></entry><entry>
Tokens that appears as phrases (with blank in them) gets
structure phrase attached. Tokens that appers as words
This sets Bib-1 relation attribute accordingly (relation
ordered). A query construct is only treated as a range if
dash is used and that is surrounded by white-space. So
- <literal>-1980</literal> is treated as term
+ <literal>-1980</literal> is treated as term
<literal>"-1980"</literal> not <literal><= 1980</literal>.
If <literal>- 1980</literal> is used, however, that is
treated as a range.
</entry>
</row>
-
+
<row><entry><literal>r=r</literal></entry><entry>
Similar to <literal>r=o</literal> but assumes that terms
are non-negative (not prefixed with <literal>-</literal>).
<literal>r=r</literal> is available in YAZ 2.0.24 or later.
</entry>
</row>
-
+
<row><entry><literal>t=l</literal></entry><entry>
Allows term to be left-truncated.
If term is of the form <literal>?x</literal>, the resulting
Type-1 term is <literal>x</literal> and truncation is left.
</entry>
</row>
-
+
<row><entry><literal>t=r</literal></entry><entry>
Allows term to be right-truncated.
If term is of the form <literal>x?</literal>, the resulting
Type-1 term is <literal>x</literal> and truncation is right.
</entry>
</row>
-
+
<row><entry><literal>t=n</literal></entry><entry>
If term is does not include <literal>?</literal>, the
truncation attribute is set to none (100).
</entry>
</row>
-
+
<row><entry><literal>t=b</literal></entry><entry>
Allows term to be both left&right truncated.
If term is of the form <literal>?x?</literal>, the
<para>
Consider the following definition:
</para>
-
+
<screen>
ti u=4 s=1
au u=1 s=1
date u=30 r=o
</screen>
<para>
- <literal>ti</literal> and <literal>au</literal> both set
+ <literal>ti</literal> and <literal>au</literal> both set
structure attribute to phrase (s=1).
<literal>ti</literal>
sets the use-attribute to 4. <literal>au</literal> sets the
</para>
<para>
You can combine attributes. To Search for "ranked title" you
- can do
+ can do
<screen>
ti,ranked=knuth computer
</screen>
A qualifier alias is of the form:
</para>
<para>
- <replaceable>q</replaceable>
+ <replaceable>q</replaceable>
<replaceable>q1</replaceable> <replaceable>q2</replaceable> ..
</para>
<para>
which declares <replaceable>q</replaceable> to
- be an alias for <replaceable>q1</replaceable>,
+ be an alias for <replaceable>q1</replaceable>,
<replaceable>q2</replaceable>... such that the CCL
query <replaceable>q=x</replaceable> is equivalent to
<replaceable>q1=x or q2=x or ...</replaceable>.
</para>
<tip>
<para>
- If you are new to CQL, read the
+ If you are new to CQL, read the
<ulink url="&url.cql.intro;">Gentle Introduction</ulink>.
</para>
</tip>
uses a <literal>FILE</literal> handle which is opened for reading.
</para>
</sect3>
-
+
<sect3 id="cql.tree"><title>CQL tree</title>
<para>
The the query string is valid, the CQL parser
a pointer to the root node of the resulting tree.
</para>
<para>
- Each node in a CQL tree is represented by a
+ Each node in a CQL tree is represented by a
<literal>struct cql_node</literal>.
It is defined as follows:
<synopsis>
<para>
Conversion to PQF (and Z39.50 RPN) is tricky by the fact
that the resulting RPN depends on the Z39.50 target
- capabilities (combinations of supported attributes).
+ capabilities (combinations of supported attributes).
In addition, the CQL and SRU operates on index prefixes
(URI or strings), whereas the RPN uses Object Identifiers
for attribute sets.
either an already open FILE or from a filename respectively.
</para>
<para>
- The handle is destroyed by <function>cql_transform_close</function>
+ The handle is destroyed by <function>cql_transform_close</function>
in which case no further reference of the handle is allowed.
</para>
<para>
int cql_transform_buf(cql_transform_t ct,
struct cql_node *cn, char *out, int max);
</synopsis>
- This function converts the CQL tree <literal>cn</literal>
+ This function converts the CQL tree <literal>cn</literal>
using handle <literal>ct</literal>.
For the resulting PQF, you supply a buffer <literal>out</literal>
which must be able to hold at at least <literal>max</literal>
<sect3 id="cql.to.rpn">
<title>Specification of CQL to RPN mappings</title>
<para>
- The file supplied to functions
+ The file supplied to functions
<function>cql_transform_open_FILE</function>,
<function>cql_transform_open_fname</function> follows
a structure found in many Unix utilities.
</term>
<listitem>
<para>
- This pattern is invoked when a CQL index, such as
+ This pattern is invoked when a CQL index, such as
dc.title is converted. <replaceable>set</replaceable>
and <replaceable>name</replaceable> are the context set and index
name respectively.
If this pattern is not defined, the mapping will fail.
</para>
<para>
- The pattern,
+ The pattern,
<literal>index.</literal><replaceable>set</replaceable><literal>.*</literal>
is used when no other index pattern is matched.
</para>
<para>
This pattern specifies how a CQL structure is mapped to RPN.
Note that this CQL pattern is somewhat to similar to
- CQL pattern <literal>relation</literal>.
+ CQL pattern <literal>relation</literal>.
The <replaceable>type</replaceable> is a CQL relation.
</para>
<para>
<listitem>
<para>
This specification defines a CQL context set for a given prefix.
- The value on the right hand side is the URI for the set -
+ The value on the right hand side is the URI for the set -
<emphasis>not</emphasis> RPN. All prefixes used in
index patterns must be defined this way.
</para>
index.cql.serverChoice = 1=1016
index.dc.title = 1=4
index.dc.subject = 1=21
-
+
relation.< = 2=1
relation.eq = 2=3
relation.scr = 2=3
containing XCQL).
<synopsis>
int cql_to_xml_buf(struct cql_node *cn, char *out, int max);
-void cql_to_xml(struct cql_node *cn,
+void cql_to_xml(struct cql_node *cn,
void (*pr)(const char *buf, void *client_data),
void *client_data);
void cql_to_xml_stdio(struct cql_node *cn, FILE *f);
<para>
The basic YAZ representation of an OID is an array of integers,
- terminated with the value -1. This integer is of type
+ terminated with the value -1. This integer is of type
<literal>Odr_oid</literal>.
</para>
<para>
Odr_oid *odr_oiddup(ODR odr, const Odr_oid *o);
</screen>
</para>
-
+
<para>
OIDs can be compared with <function>oid_oidcmp</function> which returns
zero if the two OIDs provided are identical; non-zero otherwise.
</para>
-
+
<sect2 id="tools.oid.database"><title>OID database</title>
<para>
From YAZ version 3 and later, the oident system has been replaced
convert from string to OID or other way around.
</para>
<para>
- Unfortunately, whenever we supply a string we must also specify the
+ Unfortunately, whenever we supply a string we must also specify the
<emphasis>OID class</emphasis>. The class is necessary because some
strings correspond to multiple OIDs. An example of such a string is
- <literal>Bib-1</literal> which may either be an attribute-set
+ <literal>Bib-1</literal> which may either be an attribute-set
or a diagnostic-set.
</para>
<para>
- Applications using the YAZ database should include
+ Applications using the YAZ database should include
<filename>yaz/oid_db.h</filename>.
</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.
YAZ has a built-in database which can be considered "constant" for
- most purposes.
+ most purposes.
We can get hold that by using function <function>yaz_oid_std</function>.
</para>
<para>
We can create an OID for the Bib-1 attribute set on the ODR stream
odr with:
<screen>
- Odr_oid *bib1 =
+ Odr_oid *bib1 =
yaz_string_to_oid_odr(yaz_oid_std(), CLASS_ATTSET, "Bib-1", odr);
</screen>
This is more complex than using <function>odr_getoidbystr</function>.
</sect2>
<sect2 id="tools.oid.std"><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
<emphasis>not</emphasis> call <function>nmem_init</function> or
<function>nmem_exit</function> unless you're absolute sure what
you're doing. Note that in previous &yaz; versions you'd have to call
- <function>nmem_init</function> yourself.
+ <function>nmem_init</function> yourself.
</para>
</sect1>
<sect1 id="tools.log"><title>Log</title>
<para>
- &yaz; has evolved a fairly complex log system which should be useful both
+ &yaz; has evolved a fairly complex log system which should be useful both
for debugging &yaz; itself, debugging applications that use &yaz;, and for
- production use of those applications.
+ production use of those applications.
</para>
<para>
The log functions are declared in header <filename>yaz/log.h</filename>
logged. This string should be a comma-separated list of log level names,
and can contain both hard-coded names and dynamic ones. The log level
calculation starts with <literal>YLOG_DEFAULT_LEVEL</literal> and adds a bit
- for each word it meets, unless the word starts with a '-', in which case it
+ for each word it meets, unless the word starts with a '-', in which case it
clears the bit. If the string <literal>'none'</literal> is found,
all bits are cleared. Typically this string comes from the command-line,
often identified by <literal>-v</literal>. The
</para>
<para>
- Each module should check what log bits it should be used, by calling
+ Each module should check what log bits it 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,
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
to yaz_log. (It can also be tested, so as to avoid unnecessary calls to
- yaz_log, in time-critical places, or when the log entry would take time
- to construct.)
+ yaz_log, in time-critical places, or when the log entry would take time
+ to construct.)
</para>
<para>
<para>
The log system is almost independent of the rest of &yaz;, the only
important dependence is of <filename>nmem</filename>, and that only for
- using the semaphore definition there.
+ using the semaphore definition there.
</para>
<para>
The dynamic log levels and log rotation were introduced in &yaz; 2.0.28. At
the same time, the log bit names were changed from
- <literal>LOG_something</literal> to <literal>YLOG_something</literal>,
+ <literal>LOG_something</literal> to <literal>YLOG_something</literal>,
to avoid collision with <filename>syslog.h</filename>.
</para>
</sect1>
-
+
<sect1 id="marc"><title>MARC</title>
-
+
<para>
YAZ provides a fast utility for working with MARC records.
Early versions of the MARC utility only allowed decoding of ISO2709.
</variablelist>
</para>
<para>
- The actual conversion functions are
+ 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
<literal>collection</literal>.
</para></listitem>
<listitem><para>
- The leader is encoded as element <literal>l</literal> with the
+ The leader is encoded as element <literal>l</literal> with the
leader content as its (text) value.
</para></listitem>
<listitem><para>
YAZ version 2.1.20 or later includes a Retrieval facility tool
which allows a SRU/Z39.50 to describe itself and perform record
conversions. The idea is the following:
-
+
<itemizedlist>
<listitem>
<para>
<sect2 id="tools.retrieval.format">
<title>Retrieval XML format</title>
<para>
- All elements should be covered by namespace
+ All elements should be covered by namespace
<literal>http://indexdata.com/yaz</literal> .
The root element node must be <literal>retrievalinfo</literal>.
</para>
<para>
The <literal>retrievalinfo</literal> must include one or
- more <literal>retrieval</literal> elements. Each
+ more <literal>retrieval</literal> elements. Each
<literal>retrieval</literal> defines specific combination of
syntax, name and identifier supported by this retrieval service.
</para>
</variablelist>
</para>
<para>
- The <literal>retrieval</literal> may include one
+ The <literal>retrieval</literal> may include one
<literal>backend</literal> element. If a <literal>backend</literal>
element is given, it specifies how the records are retrieved by
some backend and how the records are converted from the backend to
<varlistentry><term><literal>marc</literal></term>
<listitem>
<para>
- The <literal>marc</literal> element specifies a conversion
- to - and from ISO2709 encoded MARC and
+ The <literal>marc</literal> element specifies a conversion
+ to - and from ISO2709 encoded MARC and
<ulink url="&url.marcxml;">&acro.marcxml;</ulink>/MarcXchange.
The following attributes may be specified:
<varlistentry><term><literal>inputformat</literal> (REQUIRED)</term>
<listitem>
<para>
- Format of input. Supported values are
+ Format of input. Supported values are
<literal>marc</literal> (for ISO2709); and <literal>xml</literal>
for MARCXML/MarcXchange.
</para>
<varlistentry><term><literal>outputformat</literal> (REQUIRED)</term>
<listitem>
<para>
- Format of output. Supported values are
- <literal>line</literal> (MARC line format);
+ Format of output. Supported values are
+ <literal>line</literal> (MARC line format);
<literal>marcxml</literal> (for MARCXML),
<literal>marc</literal> (ISO2709),
<literal>marcxhcange</literal> (for MarcXchange).
<para>
It should be easy to use the retrieval systems from applications. Refer
to the headers
- <filename>yaz/retrieval.h</filename> and
+ <filename>yaz/retrieval.h</filename> and
<filename>yaz/record_conv.h</filename>.
</para>
</sect2>
</sect1>
</chapter>
-
+
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
<productnumber>&version;</productnumber>
<info><orgname>Index Data</orgname></info>
</refentryinfo>
-
+
<refmeta>
<refentrytitle>yaz-asncomp</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">Commands</refmiscinfo>
</refmeta>
-
+
<refnamediv>
<refname>yaz-asncomp</refname>
<refpurpose>YAZ ASN.1 compiler</refpurpose>
</refnamediv>
-
+
<refsynopsisdiv>
<cmdsynopsis>
<command>yaz-asncomp</command>
<arg choice="opt"><option>-m <replaceable>module</replaceable></option></arg>
<arg choice="opt">filename</arg>
</cmdsynopsis>
-
+
</refsynopsisdiv>
<refsect1><title>DESCRIPTION</title>
<para>
<listitem>
<para>
Makes the ASN.1 compiler print more verbose about the
- various stages of operations.
+ various stages of operations.
</para>
</listitem>
</varlistentry>
-
+
<varlistentry><term><literal>-c </literal>
<replaceable>cfile</replaceable></term>
<listitem><para>
Specifies the name of the C/C++ file with encoders/decoders.
</para></listitem>
</varlistentry>
-
+
<varlistentry><term><literal>-h </literal>
<replaceable>hfile</replaceable></term>
<listitem><para>
Specifies the name of header file with definitions.
</para></listitem>
</varlistentry>
-
+
<varlistentry><term><literal>-p </literal>
<replaceable>pfile</replaceable></term>
<listitem><para>
in header file (option -h).
</para></listitem>
</varlistentry>
-
+
<varlistentry><term><literal>-d </literal>
<replaceable>dfile</replaceable></term>
<listitem><para>
Specifies the name of a definitions file.
</para></listitem>
</varlistentry>
-
+
<varlistentry><term><literal>-I </literal>
<replaceable>iout</replaceable></term>
<listitem><para>
are written.
</para></listitem>
</varlistentry>
-
+
<varlistentry><term><literal>-i </literal>
<replaceable>idir</replaceable></term>
<listitem><para>
are written.
</para></listitem>
</varlistentry>
-
+
<varlistentry><term><literal>-m </literal>
<replaceable>module</replaceable></term>
<listitem><para>
all modules in the ASN.1 file are processed.
</para></listitem>
</varlistentry>
-
+
</variablelist>
</refsect1>
<refsect1><title>DEFINITIONS FILE</title>
<para>
Available variables are:
<variablelist>
-
+
<varlistentry><term><literal>default-prefix</literal></term>
<listitem><para>
Sets prefix for names in the produced output.
C typedef prefix and preprocessor prefix respectively.
</para></listitem>
</varlistentry>
-
+
<varlistentry><term><literal>prefix(</literal><replaceable>module</replaceable><literal>)</literal></term>
<listitem><para>
This value sets prefix values for module
The value has same form as <literal>default-prefix</literal>.
</para></listitem>
</varlistentry>
-
+
<varlistentry><term><literal>filename(</literal><replaceable>module</replaceable><literal>)</literal></term>
<listitem><para>
Specifies filename for C/header file for module
<replaceable>module</replaceable>.
</para></listitem>
</varlistentry>
-
+
<varlistentry><term><literal>init(</literal><replaceable>module</replaceable><literal>,h)</literal></term>
<listitem><para>
- Code fragment to be put in first part of public header for module
+ Code fragment to be put in first part of public header for module
<replaceable>module</replaceable>.
</para></listitem>
</varlistentry>
-
+
<varlistentry><term><literal>body(</literal><replaceable>module</replaceable><literal>,h)</literal></term>
<listitem><para>
- Code fragment to be put in last part of public header for module
+ Code fragment to be put in last part of public header for module
<replaceable>module</replaceable> (trailer).
</para></listitem>
</varlistentry>
module <replaceable>module</replaceable>.
</para></listitem>
</varlistentry>
-
+
<varlistentry><term><literal>body(</literal><replaceable>module</replaceable><literal>,c)</literal></term>
<listitem><para>
Code fragment to be put in last part of C based encoder/decoder for
module <replaceable>module</replaceable> (trailer).
</para></listitem>
</varlistentry>
-
+
<varlistentry><term><literal>map(</literal><replaceable>module</replaceable><literal>,</literal><replaceable>name</replaceable><literal>)</literal></term>
<listitem><para>
- Maps ASN.1 type in module <replaceable>module</replaceable>
+ Maps ASN.1 type in module <replaceable>module</replaceable>
of <replaceable>name</replaceable> to value.
</para></listitem>
</varlistentry>
-
+
<varlistentry><term><literal>membermap(</literal><replaceable>module</replaceable><literal>,</literal><replaceable>name</replaceable><literal>,</literal><replaceable>member</replaceable><literal>)</literal></term>
<listitem><para>
Maps member <replaceable>member</replaceable> in SEQUENCE/CHOICE of
C <literal>struct</literal>,<literal>union</literal>.
</para></listitem>
</varlistentry>
-
+
<varlistentry><term><literal>unionmap(</literal><replaceable>module</replaceable><literal>,</literal><replaceable>name</replaceable><literal>,</literal><replaceable>member</replaceable><literal>)</literal></term>
<listitem><para>
Maps member <replaceable>member</replaceable> in CHOICE of
-<!--
+<!--
Commands for YAZ client.
Included in both manual and man page for yaz-client.
-->
If no <literal>=</literal> is in the criterion it is treated as a
sortfield of type InternationalString.
The flags word of each sort specification must consist of
- <literal>s</literal>
+ <literal>s</literal>
for case sensitive or <literal>i</literal> for case insensitive, and
<literal><</literal> for ascending order or <literal>></literal>
for descending order.
<listitem>
<para>Sets up a authentication string if a server requires
authentication (v2 OpenStyle). The authentication string is first
- sent to the server when the
+ sent to the server when the
<link linkend="command-open"><literal>open</literal></link> command is
issued and the Z39.50 Initialize Request is sent, so this command
must be used before <literal>open</literal> in order to be effective.
<literal>GET</literal>, <literal>SOAP</literal> (default)
or <literal>SOLR</literal>. Version
should be either 1.1 or 1.2 for SRU. Other versions are allowed - for testing
- purposes (version negotiation with SRU server).
+ purposes (version negotiation with SRU server).
The version is currently not used for SOLR Web Services
</para>
</listitem>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry><term>
<literal>lslb</literal> <replaceable>n</replaceable>
</term>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry><term>
<literal>mspn</literal> <replaceable>n</replaceable>
</term>
<literal>querytype</literal> <replaceable>type</replaceable>
</term>
<listitem>
- <para>Sets the query type as used by command
+ <para>Sets the query type as used by command
<link linkend="command-find"><literal>find</literal></link>.
The following is supported:
<literal>prefix</literal> for
<replaceable>type</replaceable> <replaceable>no</replaceable>
</term>
<listitem>
- <para>Sends an Item Order Request using the ILL External.
+ <para>Sends an Item Order Request using the ILL External.
<replaceable>type</replaceable> is either 1 or 2 which corresponds to
ILL-Profile 1 and 2 respectively. The <replaceable>no</replaceable>
is the Result Set position of the record to be ordered.
<para>Sends Item Update Request. The <replaceable>action</replaceable>
argument must be the action type: one of <literal>insert</literal>,
<literal>replace</literal>, <literal>delete</literal> and
- <literal>update</literal>. The second argument,
+ <literal>update</literal>. The second argument,
<replaceable>recid</replaceable>, is the
record identifier (any string). Third argument which is optional is
- the record document for the request. If doc is preceded with
+ the record document for the request. If doc is preceded with
"<", then the following characters are treated as a filename
with the records to be updated. Otherwise doc is treated as
a document itself. The doc may also be quited in double quotes.
By default YAZ client waits (on) for response packages immediately
after a command (find, show) has been issued. If <literal>off</literal>
is used, YAZ client does not attempt to receive packages automatically.
- These will have to be manually received when command
+ These will have to be manually received when command
<link linkend="command-wait-response">
<literal>wait_response</literal>
</link> is used.
</term>
<listitem>
<para>Specifies character set for output (display). The
- argument is the same as second argument for command
+ argument is the same as second argument for command
<link linkend="command-charset"><literal>charset</literal></link>.
</para>
</listitem>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry><term>
<literal>set_cclfile</literal>
<replaceable>filename</replaceable>
<listitem>
<para>This command makes YAZ client wait for a number of
response packages from target. If <replaceable>number</replaceable> is
- omitted, 1 is assumed.
+ omitted, 1 is assumed.
</para>
<para>This command is rarely used and is only useful if command
<link linkend="command-set-auto-wait">
<replaceable>ver</replaceable>
</term>
<listitem>
- <para>This command sets Z39.50 version for negotiation.
- Should be used before
+ <para>This command sets Z39.50 version for negotiation.
+ Should be used before
<link linkend="command-open"><literal>open</literal></link>.
By default 3 (version 3) is used.
</para>
<replaceable>op1 op2..</replaceable>
</term>
<listitem>
- <para>This command sets Z39.50 options for negotiation.
- Should be used before
+ <para>This command sets Z39.50 options for negotiation.
+ Should be used before
<link linkend="command-open"><literal>open</literal></link>.
</para>
<para>
The following options are supported:
- <literal>search</literal>,
- <literal>present</literal>,
- <literal>delSet</literal>,
- <literal>resourceReport</literal>,
- <literal>triggerResourceCtrl</literal>,
- <literal>resourceCtrl</literal>,
- <literal>accessCtrl</literal>,
- <literal>scan</literal>,
- <literal>sort</literal>,
- <literal>extendedServices</literal>,
- <literal>level_1Segmentation</literal>,
- <literal>level_2Segmentation</literal>,
- <literal>concurrentOperations</literal>,
- <literal>namedResultSets</literal>,
- <literal>encapsulation</literal>,
- <literal>resultCount</literal>,
- <literal>negotiationModel</literal>,
- <literal>duplicationDetection</literal>,
- <literal>queryType104</literal>,
- <literal>pQESCorrection</literal>,
+ <literal>search</literal>,
+ <literal>present</literal>,
+ <literal>delSet</literal>,
+ <literal>resourceReport</literal>,
+ <literal>triggerResourceCtrl</literal>,
+ <literal>resourceCtrl</literal>,
+ <literal>accessCtrl</literal>,
+ <literal>scan</literal>,
+ <literal>sort</literal>,
+ <literal>extendedServices</literal>,
+ <literal>level_1Segmentation</literal>,
+ <literal>level_2Segmentation</literal>,
+ <literal>concurrentOperations</literal>,
+ <literal>namedResultSets</literal>,
+ <literal>encapsulation</literal>,
+ <literal>resultCount</literal>,
+ <literal>negotiationModel</literal>,
+ <literal>duplicationDetection</literal>,
+ <literal>queryType104</literal>,
+ <literal>pQESCorrection</literal>,
<literal>stringSchema</literal>.
</para>
</listitem>
</varlistentry>
-
+
</variablelist>
<!-- Keep this comment at the end of the file
Local variables:
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
[
<!ENTITY % local SYSTEM "local.ent">
<productnumber>&version;</productnumber>
<info><orgname>Index Data</orgname></info>
</refentryinfo>
-
+
<refmeta>
<refentrytitle>yaz-client</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">Commands</refmiscinfo>
</refmeta>
-
+
<refnamediv>
<refname>yaz-client</refname>
<refpurpose>Z39.50/SRU client for implementors</refpurpose>
</cmdsynopsis>
</refsynopsisdiv>
-
+
<refsect1><title>DESCRIPTION</title>
<para>
<command>yaz-client</command> is a
commands from one of the following files:
<itemizedlist>
<listitem><para>
- Command file if it is given by option -f.
+ Command file if it is given by option -f.
</para></listitem>
<listitem><para>
<filename>.yazclientrc</filename> in current working directory.
<varlistentry>
<term>-d <replaceable>dump</replaceable></term>
<listitem><para>
- If specified, YAZ will dump BER data for all PDUs sent and received
+ If specified, YAZ will dump BER data for all PDUs sent and received
to individual files, named
- <replaceable>dump</replaceable>.DDD.<literal>raw</literal>,
+ <replaceable>dump</replaceable>.DDD.<literal>raw</literal>,
where DDD is 001, 002, 003, ..
</para></listitem>
</varlistentry>
<listitem><para>
If specified, the client will use the proxy at the address
given. YAZ client will
- connect to a proxy on the address and port given.
+ connect to a proxy on the address and port given.
The actual target will be specified as part of the InitRequest
to inform the proxy about actual target.
</para></listitem>
<term>-t <replaceable>displaycharset</replaceable></term>
<listitem><para>
If displaycharset is given, it specifies name of the character set of the
- output (on the terminal on which YAZ client is running).
+ output (on the terminal on which YAZ client is running).
</para></listitem>
</varlistentry>
<varlistentry>
</term><listitem>
<simpara>Sets the LOG level to <replaceable>level</replaceable>.
Level is a sequence of tokens separated by comma. Each token
- is a integer or a named LOG item - one of
+ is a integer or a named LOG item - one of
<literal>fatal</literal>,
<literal>debug</literal>,
<literal>warn</literal>,
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
-[
+[
<!ENTITY % local SYSTEM "local.ent">
%local;
<!ENTITY % entities SYSTEM "entities.ent">
<productnumber>&version;</productnumber>
<info><orgname>Index Data</orgname></info>
</refentryinfo>
-
+
<refmeta>
<refentrytitle>yaz-config</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">Commands</refmiscinfo>
</refmeta>
-
+
<refnamediv>
<refname>yaz-config</refname>
<refpurpose>Script to get information about YAZ.</refpurpose>
</refnamediv>
-
+
<refsynopsisdiv>
<cmdsynopsis>
<command>yaz-config</command>
<arg choice="opt" rep="repeat">libraries</arg>
</cmdsynopsis>
</refsynopsisdiv>
-
+
<refsect1><title>DESCRIPTION</title>
<para>
<command>yaz-config</command> is a script that returns information
</para></listitem>
</varlistentry>
</variablelist>
-
+
</refsect1>
-
+
<refsect1><title>OPTIONS</title>
-
+
<variablelist>
<varlistentry>
<term>--prefix[=<replaceable>DIR</replaceable>]</term>
</variablelist>
</refsect1>
-
+
<refsect1><title>FILES</title>
<para>
<filename>&prefix;/bin/yaz-config</filename>
<productnumber>&version;</productnumber>
<info><orgname>Index Data</orgname></info>
</refentryinfo>
-
+
<refmeta>
<refentrytitle>yaz-iconv</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">Commands</refmiscinfo>
</refmeta>
-
+
<refnamediv>
<refname>yaz-iconv</refname>
<refpurpose>YAZ Character set conversion utility</refpurpose>
</refnamediv>
-
+
<refsynopsisdiv>
<cmdsynopsis>
<command>yaz-iconv</command>
<arg choice="opt" rep="repeat">file</arg>
</cmdsynopsis>
</refsynopsisdiv>
-
+
<refsect1><title>DESCRIPTION</title>
<para>
<command>yaz-iconv</command> converts data in file in character
<command>yaz-iconv</command> reads from standard input.
</para>
</refsect1>
-
+
<refsect1><title>OPTIONS</title>
-
+
<variablelist>
<varlistentry>
<term>-f<replaceable>from</replaceable>]</term>
</variablelist>
</refsect1>
-
+
<refsect1><title>ENCODINGS</title>
<para>
The yaz-iconv command and the API as defined in
yaz-iconv -f ISO-8859-1 -t UTF-8 -X <input.lst >output.lst
</screen>
</para>
- </refsect1>
+ </refsect1>
<refsect1><title>FILES</title>
<para>
<productnumber>&version;</productnumber>
<info><orgname>Index Data</orgname></info>
</refentryinfo>
-
+
<refmeta>
<refentrytitle>yaz-icu</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">Commands</refmiscinfo>
</refmeta>
-
+
<refnamediv>
<refname>yaz-icu</refname>
<refpurpose>YAZ ICU utility</refpurpose>
<arg choice="opt">infile</arg>
</cmdsynopsis>
</refsynopsisdiv>
-
+
<refsect1><title>DESCRIPTION</title>
<para>
- <command>yaz-icu</command> is utility which demonstrates
+ <command>yaz-icu</command> is utility which demonstrates
the ICU chain module of yaz. (<filename>yaz/icu.h</filename>).
</para>
<para>
<listitem><para>
Specifies extra information to be printed about the ICU system.
If <replaceable>type</replaceable> is <literal>c</literal>
- then ICU converters are printed.
+ then ICU converters are printed.
If <replaceable>type</replaceable> is <literal>l</literal>
available locales are printed.
If <replaceable>type</replaceable> is <literal>t</literal>
</para>
<para>
The following conversion elements are available:
-
+
<variablelist>
<varlistentry>
<term>casemap</term>
<para>Upper case using ICU function u_strToUpper.</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>t</term>
<listitem>
<para>Fold case using ICU function u_strFoldCase.</para>
</listitem>
</varlistentry>
-
+
</variablelist>
</para></listitem>
</varlistentry>
using function icu_chain_token_display (<filename>yaz/icu.h</filename>).
</para></listitem>
</varlistentry>
-
+
<varlistentry>
<term>transform</term>
<listitem><para>
more information.
</para></listitem>
</varlistentry>
-
+
<varlistentry>
<term>transliterate</term>
<listitem><para>
more information.
</para></listitem>
</varlistentry>
-
+
<varlistentry>
<term>tokenize</term>
<listitem><para>
<para>Sentence. ICU: UBRK_SENTENCE.</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>w</term>
<listitem>
</variablelist>
</para></listitem>
</varlistentry>
-
+
</variablelist>
-
+
</para>
</refsect1>
<refsect1><title>EXAMPLES</title>
<productnumber>&version;</productnumber>
<info><orgname>Index Data</orgname></info>
</refentryinfo>
-
+
<refmeta>
<refentrytitle>yaz-illclient</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">Commands</refmiscinfo>
</refmeta>
-
+
<refnamediv>
<refname>yaz-illclient</refname>
<refpurpose>ILL client</refpurpose>
</refnamediv>
-
+
<refsynopsisdiv>
<cmdsynopsis>
<command>yaz-illclient</command>
<arg choice="opt" rep="repeat"><option>-D</option> <replaceable>name=value</replaceable></arg>
<arg choice="opt"><option>-o</option></arg>
<arg choice="opt"><option>-u <replaceable>user</replaceable></option></arg>
- <arg choice="opt"><option>-p <replaceable>password</replaceable></option></arg>
+ <arg choice="opt"><option>-p <replaceable>password</replaceable></option></arg>
<arg choice="opt"><option>-V</option></arg>
<arg choice="opt">server-addr</arg>
</cmdsynopsis>
</refsynopsisdiv>
-
+
<refsect1><title>DESCRIPTION</title>
<para>
<command>yaz-illclient</command> is an client which sends an ISO
must be specified.
</para>
</refsect1>
-
+
<refsect1><title>OPTIONS</title>
-
+
<variablelist>
<varlistentry>
<term>-f <replaceable>filename</replaceable>]</term>
<para>
None yet.
</para>
- </refsect1>
+ </refsect1>
<refsect1><title>FILES</title>
<para>
<productnumber>&version;</productnumber>
<info><orgname>Index Data</orgname></info>
</refentryinfo>
-
+
<refmeta>
<refentrytitle>yaz-json-parse</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">Commands</refmiscinfo>
</refmeta>
-
+
<refnamediv>
<refname>yaz-json-parse</refname>
<refpurpose>YAZ JSON parser</refpurpose>
<arg>-p</arg>
</cmdsynopsis>
</refsynopsisdiv>
-
+
<refsect1><title>DESCRIPTION</title>
<para>
- <command>yaz-json-parse</command> is utility which demonstrates
+ <command>yaz-json-parse</command> is utility which demonstrates
the JSON API of YAZ. (<filename>yaz/json.h</filename>).
</para>
<para>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
-[
+[
<!ENTITY % local SYSTEM "local.ent">
%local;
<!ENTITY % entities SYSTEM "entities.ent">
<productnumber>&version;</productnumber>
<info><orgname>Index Data</orgname></info>
</refentryinfo>
-
+
<refmeta>
<refentrytitle>yaz-log</refentrytitle>
<manvolnum>7</manvolnum>
<refmiscinfo class="manual">Conventions and miscellaneous</refmiscinfo>
</refmeta>
-
+
<refnamediv>
<refname>yaz-log</refname>
<refpurpose>Log handling in all yaz-based programs</refpurpose>
</refnamediv>
-
+
<refsynopsisdiv>
<cmdsynopsis>
<command>yaz-XXXX</command>
<arg choice="opt"><option>-l <replaceable>logfile</replaceable></option></arg>
</cmdsynopsis>
</refsynopsisdiv>
-
+
<refsect1><title>DESCRIPTION</title>
<para>
All YAZ-based programs use a common log subsystem, and should support
<para>
</para>
</refsect1>
-
+
<refsect1><title>OPTIONS</title>
-
+
<variablelist>
<varlistentry>
<term>-l<replaceable> logfile</replaceable></term>
<filename>stderr</filename> is used. The log is appended to this file.
If the file grows overly large, it is silently rotated: It is renamed to
<replaceable>logfile</replaceable>.1,
- <replaceable>logfile</replaceable>.2, .., 9
+ <replaceable>logfile</replaceable>.2, .., 9
(old such file is deleted), and a
new file is opened. The limit defaults to 1GB, but can be set by the
program.
<refsect1><title>LOG LEVELS TO CONTROL LOGGING</title>
<para>
- Some of the log levels control the way the log is written.
+ Some of the log levels control the way the log is written.
</para>
<para>
<literal>flush</literal> causes the log to be flushed after every write.
intended for automatic test scripts, which should produce predictable log
files that are easy to compare.
</para>
-
- </refsect1>
+
+ </refsect1>
<refsect1><title>GENERAL LOG LEVELS IN YAZ ITSELF</title>
<para>
levels (see below).
</para>
<para>
- <literal>all</literal> turns on almost all hard-coded log levels.
+ <literal>all</literal> turns on almost all hard-coded log levels.
</para>
<para>
<literal>loglevel</literal> logs information about the log levels used by
is to grep for <function>yaz_log_module_level</function> in the source
code, as in
<screen>
- find . -name '*.[ch]' -print |
- xargs grep yaz_log_module_level |
+ find . -name '*.[ch]' -print |
+ xargs grep yaz_log_module_level |
grep '"' |
- cut -d'"' -f2 |
- sort -u
+ cut -d'"' -f2 |
+ sort -u
</screen>
</para>
<para>
- <literal>eventl</literal>, <literal>malloc</literal>,
+ <literal>eventl</literal>, <literal>malloc</literal>,
<literal>nmem</literal>, <literal>odr</literal> are used internally for
debugging yaz.
</para>
<para>
</para>
- </refsect1>
+ </refsect1>
<refsect1><title>LOG LEVELS FOR CLIENTS</title>
<para>
<literal>zoom</literal> logs the calls to the zoom API, which may be useful
in debugging client applications.
</para>
- </refsect1>
+ </refsect1>
<refsect1><title>LOG LEVELS FOR SERVERS</title>
<para>
14:45:41-23/11 yaz-ztest [requestdetail] Request to pack 1+1 1
14:45:41-23/11 yaz-ztest [requestdetail] pms=1048576, mrs=1048576
14:45:41-23/11 yaz-ztest [request] Present: [1] 1+1 OK 1 records returned
- </screen>
+ </screen>
</para>
- </refsect1>
+ </refsect1>
<refsect1><title>LOG FILENAME EXAMPLES</title>
<para>
is depending on day, rotaion will occur on midnight.
</para>
<para>
- A weekly log could be specified as
+ A weekly log could be specified as
<literal>-l my_%Y%U.log</literal>.
</para>
</refsect1>
-
+
<refsect1><title>FILES</title>
<para>
<filename><replaceable>prefix</replaceable>/include/yaz/log.h</filename>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
[
<!ENTITY % local SYSTEM "local.ent">
<productnumber>&version;</productnumber>
<info><orgname>Index Data</orgname></info>
</refentryinfo>
-
+
<refmeta>
<refentrytitle>yaz</refentrytitle>
<manvolnum>7</manvolnum>
<refmiscinfo class="manual">Conventions and miscellaneous</refmiscinfo>
</refmeta>
-
+
<refnamediv>
<refname>yaz</refname>
<refpurpose>Z39.50 toolkit.</refpurpose>
</refnamediv>
-
+
<refsect1><title>DESCRIPTION</title>
<para>
YAZ is a C/C++ programmer's toolkit supporting the development
<para>
All rights reserved.
</para>
-
+
<para>
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
</para>
-
+
<itemizedlist>
<listitem>
<para>
</para>
</listitem>
</itemizedlist>
-
+
<para>
THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
</para>
-
+
</refsect1>
-
+
<refsect1><title>SEE ALSO</title>
<para>
<citerefentry>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">Commands</refmiscinfo>
</refmeta>
-
+
<refnamediv>
<refname>yaz-marcdump</refname>
<refpurpose>MARC record dump utility</refpurpose>
</refnamediv>
-
+
<refsynopsisdiv>
<cmdsynopsis>
<command>yaz-marcdump</command>
<arg choice="opt" rep="repeat">file</arg>
</cmdsynopsis>
</refsynopsisdiv>
-
+
<refsect1><title>DESCRIPTION</title>
<para>
<command>yaz-marcdump</command> reads MARC records from one or
more files.
- It parses each record and supports output in line-format,
+ It parses each record and supports output in line-format,
ISO2709, MARCXML, MarcXchange as well as Hex output.
</para>
<para>
character set conversion of each record.
</para>
</refsect1>
-
+
<refsect1><title>OPTIONS</title>
-
+
<variablelist>
<varlistentry>
<term>-i <replaceable>format</replaceable></term>
<varlistentry>
<term>-C <replaceable>chunksize</replaceable></term>
<listitem><para>
- Specifies chunk size; to be used conjunction with option
+ Specifies chunk size; to be used conjunction with option
<literal>-s</literal>.
</para></listitem>
</varlistentry>
Useful if you have ill-formatted ISO2709 records as input.
</para></listitem>
</varlistentry>
-
+
<varlistentry>
<term>-V</term>
<listitem><para>
yaz-marcdump -f MARC8 -t UTF8 -o turbomarc -i marc marc21.raw >out.xml
</screen>
</para>
- </refsect1>
+ </refsect1>
<refsect1><title>FILES</title>
<para>
<productnumber>&version;</productnumber>
<info><orgname>Index Data</orgname></info>
</refentryinfo>
-
+
<refmeta>
<refentrytitle>yaz-url</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">Commands</refmiscinfo>
</refmeta>
-
+
<refnamediv>
<refname>yaz-url</refname>
<refpurpose>YAZ URL fetch utility</refpurpose>
<arg rep="repeat">url</arg>
</cmdsynopsis>
</refsynopsisdiv>
-
+
<refsect1><title>DESCRIPTION</title>
<para>
<command>yaz-url</command> is utility to get web content. It is very
<productnumber>&version;</productnumber>
<info><orgname>Index Data</orgname></info>
</refentryinfo>
-
+
<refmeta>
<refentrytitle>yaz-ztest</refentrytitle>
<manvolnum>8</manvolnum>
<refmiscinfo class="manual">System management commands</refmiscinfo>
</refmeta>
-
+
<refnamediv>
<refname>yaz-ztest</refname>
<refpurpose>Z39.50/SRU Test Server</refpurpose>
</refnamediv>
-
+
<refsynopsisdiv>
&gfs-synopsis;
</refsynopsisdiv>
<title>TESTING</title>
<para>
<command>yaz-ztest</command> normally returns a random hit count between
- 0 and 24. However, if a query term includes leading digits, then the
+ 0 and 24. However, if a query term includes leading digits, then the
integer value of that term is used as hit count. This allows testers
to return any number of hits. <command>yaz-ztest</command> includes
- 24 MARC records for testing. Hit counts exceeding 24 will make
+ 24 MARC records for testing. Hit counts exceeding 24 will make
<command>yaz-ztest</command> return the same record batch over and over..
So record at position 1, 25, 49, etc .. are equivalent.
</para>
a random sleep between the first and second number.
</para>
<para>
- The database parameter <literal>seed</literal> takes an integer
+ The database parameter <literal>seed</literal> takes an integer
as value. This will call <literal>srand</literal> with this integer to
ensure that the random behavior can be re-played.
</para>
<?xml version="1.0" standalone="no"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
- "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
+ "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
[
<!ENTITY % local SYSTEM "local.ent">
%local;
%idcommon;
]>
<book>
- &bookinfo;
+ &bookinfo;
&chap-introduction;
&chap-installation;
&chap-zoom;
</para>
&std-oid-table;
</appendix>
-
+
&app-license;
&app-indexdata;
&app-credits;
<literal>sru=get,http://sru.miketaylor.org.uk:80/sru.pl</literal>
</para>
<para>
- <ulink url="&url.solr;">SOLR</ulink> protocol support was added to YAZ in version 4.1.0,
- as a dialect of a SRU protocol, since both are HTTP based protocols.
+ <ulink url="&url.solr;">SOLR</ulink> protocol support was added to YAZ in version 4.1.0,
+ as a dialect of a SRU protocol, since both are HTTP based protocols.
</para>
<para>
The lack of a simple Z39.50 client API for &yaz; has become more
<ulink url="&url.zoom;">ZOOM web-site</ulink> for
more information.
</para>
-
+
<para>
In order to fully understand this chapter you should read and
try the example programs <literal>zoomtst1.c</literal>,
<literal>zoomtst2.c</literal>, .. in the <literal>zoom</literal>
directory.
</para>
-
+
<para>
The C language misses features found in object oriented languages
such as C++, Java, etc. For example, you'll have to manually,
protocol.
</para>
<sect1 id="zoom-connections"><title>Connections</title>
-
+
<para>The Connection object is a session with a target.
</para>
<synopsis>
#include <yaz/zoom.h>
-
+
ZOOM_connection ZOOM_connection_new (const char *host, int portnum);
-
+
ZOOM_connection ZOOM_connection_create (ZOOM_options options);
-
+
void ZOOM_connection_connect(ZOOM_connection c, const char *host,
int portnum);
void ZOOM_connection_destroy(ZOOM_connection c);
</synopsis>
<para>
Connection objects are created with either function
- <function>ZOOM_connection_new</function> or
+ <function>ZOOM_connection_new</function> or
<function>ZOOM_connection_create</function>.
The former creates and automatically attempts to establish a network
connection with the target. The latter doesn't establish
a connection immediately, thus allowing you to specify options
before establishing network connection using the function
- <function>ZOOM_connection_connect</function>.
+ <function>ZOOM_connection_connect</function>.
If the port number, <literal>portnum</literal>, is zero, the
<literal>host</literal> is consulted for a port specification.
If no port is given, 210 is used. A colon denotes the beginning of
<para>
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.
+ The scheme <literal>http</literal> selects SRU/get over HTTP by default,
+ but can overridded to use SRU/post, SRW and the SOLR protocol.
</para>
<para>
You can prefix the scheme-qualified host-string with one or more
The functions <function>ZOOM_connection_option_set</function> and
<function>ZOOM_connection_option_setl</function> allows you to
set an option given by <parameter>key</parameter> to the value
- <parameter>value</parameter> for the connection.
+ <parameter>value</parameter> for the connection.
For <function>ZOOM_connection_option_set</function>, the
value is assumed to be a 0-terminated string. Function
<function>ZOOM_connection_option_setl</function> specifies a
of a client. Is used of 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
+ async</entry><entry>If true (1) the connection operates in
asynchronous operation which means that all calls are non-blocking
except
<link linkend="zoom.events"><function>ZOOM_event</function></link>.
facets</entry><entry>
A FacetList is comma-separated list of facet, which is defined
as <literal>AttributeList</literal> and a optional FacetTerm
- (a Term and a frequency). On request the terms is missing.
+ (a Term and a frequency). On request the terms is missing.
On response the the list contains the terms that the target
- could collect.
+ could collect.
</entry><entry>none</entry></row>
<row><entry>
apdulog</entry><entry>
</table>
<para>
If either option <literal>lang</literal> or <literal>charset</literal>
- is set, then
+ is set, then
<ulink url="&url.z39.50.charneg;">
Character Set and Language Negotiation</ulink> is in effect.
</para>
More query types will be added in future versions of &yaz;, such as
<link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
etc. In addition to a search, a sort criteria may be set. Function
- <function>ZOOM_query_sortby</function> specifies a
+ <function>ZOOM_query_sortby</function> specifies a
sort criteria using the same string notation for sort as offered by
the <link linkend="sortspec">YAZ client</link>.
</para>
The number of hits also called result-count is returned by
function <function>ZOOM_resultset_size</function>.
</para>
- <table id="zoom.resultset.options"
+ <table id="zoom.resultset.options"
frame="top"><title>ZOOM Result set Options</title>
<tgroup cols="3">
<colspec colwidth="4*" colname="name"></colspec>
</thead>
<tbody>
<row><entry>
- start</entry><entry>Offset of first record to be
+ start</entry><entry>Offset of first record to be
retrieved from target. First record has offset 0 unlike the
protocol specifications where first record has position 1.
This option affects ZOOM_resultset_search and
function ZOOM_resultset_records should be used.
</entry><entry>0</entry></row>
<row><entry>
- count</entry><entry>Number of records to be retrieved.
+ count</entry><entry>Number of records to be retrieved.
This option affects ZOOM_resultset_search and
ZOOM_resultset_search_pqf and must be set before any of
these functions are invoked.
option is also supported for the benefit of old applications.)
</entry><entry>0</entry></row>
<row><entry>
- elementSetName</entry><entry>Element-Set name of records.
+ 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>
</para>
<para>
This information is a list of of items, where each item is
- information about a term or subquery. All items in the list
- are prefixed by
+ information about a term or subquery. All items in the list
+ are prefixed by
<literal>SearchResult.</literal><replaceable>no</replaceable>
- where no presents the item number (0=first, 1=second).
+ where no presents the item number (0=first, 1=second).
Read <literal>searchresult.size</literal> to determine the
number of items.
</para>
- <table id="zoom.search.info.report.options"
+ <table id="zoom.search.info.report.options"
frame="top"><title>Search Info Report Options</title>
<tgroup cols="2">
<colspec colwidth="4*" colname="name"></colspec>
<literal>preferredRecordSyntax</literal> are ignored.
</para>
<para>
- Options <literal>start</literal> and <literal>count</literal>
+ Options <literal>start</literal> and <literal>count</literal>
are supported by SRU.
The remaining options
- <literal>piggyback</literal>,
- <literal>smallSetUpperBound</literal>,
- <literal>largeSetLowerBound</literal>,
- <literal>mediumSetPresentNumber</literal>,
+ <literal>piggyback</literal>,
+ <literal>smallSetUpperBound</literal>,
+ <literal>largeSetLowerBound</literal>,
+ <literal>mediumSetPresentNumber</literal>,
<literal>mediumSetElementSetName</literal>,
<literal>smallSetElementSetName</literal> are
unsupported.
<para>
Unfortunately, SRU or SOLR does not define a database setting. Hence,
<literal>databaseName</literal> is unsupported and ignored.
- However, the path part in host parameter for functions
+ However, the path part in host parameter for functions
<function>ZOOM_connecton_new</function> and
<function>ZOOM_connection_connect</function> acts as a
database (at least for the &yaz; SRU server).
void ZOOM_record_destroy(ZOOM_record rec);
</synopsis>
<para>
- References to temporary records are returned by functions
+ References to temporary records are returned by functions
<function>ZOOM_resultset_records</function> or
<function>ZOOM_resultset_record</function>.
</para>
</para>
<para>
A single record is returned by function
- <function>ZOOM_resultset_record</function> that takes a
+ <function>ZOOM_resultset_record</function> that takes a
position as argument. First record has position zero.
If no record could be obtained <literal>NULL</literal> is returned.
</para>
If <replaceable>to</replaceable> is omitted 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,
<replaceable>opacfrom</replaceable> should be set to the character set
<para>
The format argument controls whether record data should be XML
pretty-printed (post process operation).
- It is enabled only if format value <replaceable>v</replaceable> is
+ It is enabled only if format value <replaceable>v</replaceable> is
<literal>1</literal> and the record content is XML well-formed.
</para>
<para>
In addition, for certain types, the length
<literal>len</literal> passed will be set to the size in bytes of
- the returned information.
+ the returned information.
</para>
<para>
The following are the supported values for <replaceable>form</replaceable>.
<varlistentry><term><literal>database</literal></term>
<listitem><para>Database of record is returned
as a C null-terminated string. Return type
- <literal>const char *</literal>.
+ <literal>const char *</literal>.
</para></listitem>
</varlistentry>
<varlistentry><term><literal>syntax</literal></term>
as a C null-terminated string containing the symbolic name of
the record syntax, e.g. <literal>Usmarc</literal>. Return type
is
- <literal>const char *</literal>.
+ <literal>const char *</literal>.
</para></listitem>
</varlistentry>
<varlistentry><term><literal>schema</literal></term>
<listitem><para>The schema of the record is returned
as a C null-terminated string. Return type is
- <literal>const char *</literal>.
+ <literal>const char *</literal>.
</para></listitem>
</varlistentry>
<varlistentry><term><literal>render</literal></term>
<varlistentry><term><literal>raw</literal></term>
<listitem><para>The record is returned in the internal
YAZ specific format. For GRS-1, Explain, and others, the
- raw data is returned as type
+ raw data is returned as type
<literal>Z_External *</literal> which is just the type for
the member <literal>retrievalRecord</literal> in
type <literal>NamePlusRecord</literal>.
returned verbatim. MARC records are returned in
<ulink url="&url.marcxml;">
MARCXML
- </ulink>
+ </ulink>
(converted from ISO2709 to MARCXML by YAZ).
- OPAC records are also converted to XML and the
+ OPAC records are also converted to XML and the
bibliographic record is converted to MARCXML (when possible).
GRS-1 records are not supported for this form.
Upon completion, the XML buffer is returned
returned verbatim. MARC records are returned in
<link linkend="tools.turbomarc">
TurboMARC
- </link>
+ </link>
(converted from ISO2709 to TurboMARC by YAZ).
Upon completion, the XML buffer is returned
(type <literal>const char *</literal>) and length is stored in
<para>
Most
<ulink url="&url.marc21;">MARC21</ulink>
- records uses the
+ records uses the
<ulink url="&url.marc8;">MARC-8</ulink>
character set encoding.
An application that wishes to display in Latin-1 would use
</sect1>
<sect1 id="zoom.facets"><title>Facets</title>
<para>
- Facets operations is not part of the official ZOOM specification, but is an Index Data extension
- for YAZ-based Z39.50 targets or <ulink url="&url.solr;">SOLR</ulink> targets.
- In case the target can and is requested to return facets, using a result set the ZOOM client
- can request one or all facet fields. Using a facet field the client can request the term count and
+ Facets operations is not part of the official ZOOM specification, but is an Index Data extension
+ for YAZ-based Z39.50 targets or <ulink url="&url.solr;">SOLR</ulink> targets.
+ In case the target can and is requested to return facets, using a result set the ZOOM client
+ can request one or all facet fields. Using a facet field the client can request the term count and
then interate over the terms.
</para>
<synopsis>
const char *ZOOM_facet_field_get_term(ZOOM_facet_field facet_field, size_t idx, int *freq);
</synopsis>
<para>
- References to temporary structures are returned by all functions. They are only valid as long the Result set is valid.
+ References to temporary structures are returned by all functions. They are only valid as long the Result set is valid.
<function>ZOOM_resultset_get_facet_field</function> or
<function>ZOOM_resultset_get_facet_field_by_index</function>.
<function>ZOOM_resultset_facets</function>.
</para>
<para id="zoom.resultset.get_facet_field">
A single Facet field is returned by function
- <function>ZOOM_resultset_get_facet_field</function> or <function>ZOOM_resultset_get_facet_field_by_index</function> that takes a
+ <function>ZOOM_resultset_get_facet_field</function> or <function>ZOOM_resultset_get_facet_field_by_index</function> that takes a
result set and facet name or positive index respectively. First facet has position zero.
If no facet could be obtained (invalid name or index out of bounds) <literal>NULL</literal> is returned.
</para>
<para id="zoom.resultset.facets">
- 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
- <function>ZOOM_resultset_facets_size(result_set)</function>-1.
+ 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
+ <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 as parameter for
- <function>ZOOM_resultset_get_facet_field</function>.
+ 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 as parameter for
+ <function>ZOOM_resultset_get_facet_field</function>.
</para>
<para>
- Function <function>ZOOM_facet_field_name</function> gets the request facet name from a returned facet field.
+ Function <function>ZOOM_facet_field_name</function> gets the request facet name from a returned facet field.
</para>
<para>
- Function <function>ZOOM_facet_field_get_term</function> returns the idx'th term and term count for a facet field.
- Idx must between 0 and <function>ZOOM_facet_field_term_count</function>-1, otherwise the returned reference will be
- <literal>NULL</literal>. On a valid idx, the value of the freq reference will be the term count.
- The *freq parameter must be valid pointer to integer.
+ Function <function>ZOOM_facet_field_get_term</function> returns the idx'th term and term count for a facet field.
+ Idx must between 0 and <function>ZOOM_facet_field_term_count</function>-1, otherwise the returned reference will be
+ <literal>NULL</literal>. On a valid idx, the value of the freq reference will be the term count.
+ The *freq parameter must be valid pointer to integer.
</para>
</sect1>
<sect1 id="zoom.scan"><title>Scan</title>
a scan set offset <literal>pos</literal> and returns a pointer
to a <emphasis>raw term</emphasis> or <literal>NULL</literal> if
non-present.
- If present, the <literal>occ</literal> and <literal>len</literal>
+ If present, the <literal>occ</literal> and <literal>len</literal>
are set to the number of occurrences and the length
of the actual term respectively.
<function>ZOOM_scanset_display_term</function> is similar to
more generic alternative to <function>ZOOM_connection_scan</function>
which allows to use both CQL and PQF for Scan.
</para>
-
+
<table frame="top" id="zoom.scanset.options">
<title>ZOOM Scan Set Options</title>
<tgroup cols="3">
</para>
<para>
<function>ZOOM_package_send</function> sends
- the package the via connection specified in
+ the package the via connection specified in
<function>ZOOM_connection_package</function>.
The <parameter>type</parameter> specifies the actual extended service
package type to be sent.
<row>
<entry>action</entry>
<entry>
- The update action. One of
+ The update action. One of
<literal>specialUpdate</literal>,
<literal>recordInsert</literal>,
<literal>recordReplace</literal>,
<literal>syntax</literal> (see below).
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
+ ignored if recordOpaque is set. This option is only available in
YAZ 3.0.35 and later and is meant to facilitate Updates with
servers from OCLC.
</entry>
1, 2 or 3. Each version has a distinct OID:
1.2.840.10003.9.5
(<ulink url="&url.z39.50.extupdate1;">first version</ulink>) ,
- 1.2.840.10003.9.5.1
- (second version) and
- 1.2.840.10003.9.5.1.1
+ 1.2.840.10003.9.5.1
+ (second version) and
+ 1.2.840.10003.9.5.1.1
(<ulink url="&url.z39.50.extupdate3;">third and
newest version</ulink>).
</entry>
</tbody>
</tgroup>
</table>
-
+
</sect2>
<sect2 id="zoom.database.create"><title>Database Create</title>
For Database Create, type must be set to <literal>create</literal> in
<function>ZOOM_package_send</function>.
</para>
-
+
<table frame="top" id="zoom.database.create.options">
<title>Database Create Options</title>
<tgroup cols="3">
</tgroup>
</table>
</sect2>
-
+
<sect2 id="zoom.database.drop"><title>Database Drop</title>
<para>
For Database Drop, type must be set to <literal>drop</literal> in
<function>ZOOM_package_send</function>.
</para>
-
+
<table frame="top" id="zoom.database.drop.options">
<title>Database Drop Options</title>
<tgroup cols="3">
</tgroup>
</table>
</sect2>
-
+
<sect2 id="zoom.commit"><title>Commit Operation</title>
<para>
For Commit, type must be set to <literal>commit</literal> in
</sect1>
<sect1 id="zoom.events"><title>Events</title>
<para>
- If you're developing non-blocking applications, you have to deal
+ If you're developing non-blocking applications, you have to deal
with events.
</para>
<synopsis>
</table>
</sect1>
</chapter>
-
+
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-namecase-general:t
End:
-->
-
+
<productnumber>&version;</productnumber>
<info><orgname>Index Data</orgname></info>
</refentryinfo>
-
+
<refmeta>
<refentrytitle>zoomsh</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">Commands</refmiscinfo>
</refmeta>
-
+
<refnamediv>
<refname>zoomsh</refname>
<refpurpose>ZOOM shell</refpurpose>
</para>
<para>
You may pass one or more commands to <command>zoomsh</command>.
- These commands are invoked first.
+ These commands are invoked first.
</para>
</refsect1>
localhost:9999: 7 hits
ZOOM>show 0 1
1 Default USmarc
-001 11224466
+001 11224466
003 DLC
005 00000000000000.0
-008 910710c19910701nju 00010 eng
-010 $a 11224466
+008 910710c19910701nju 00010 eng
+010 $a 11224466
040 $a DLC $c DLC
050 00 $a 123-xyz
100 10 $a Jack Collins
</refsect1>
<refsect1><title>COMMANDS</title>
<variablelist>
-
+
<varlistentry><term><literal>connect</literal>
<replaceable>zurl</replaceable></term>
<listitem><para>
Connects to the target given by <replaceable>zurl</replaceable>.
</para></listitem></varlistentry>
-
+
<varlistentry><term><literal>close</literal>
[<replaceable>zurl</replaceable>]</term>
<listitem><para>
<replaceable>zurl</replaceable> or all targets if
<replaceable>zurl</replaceable> was omitted.
</para></listitem></varlistentry>
-
+
<varlistentry><term><literal>show</literal>
[<replaceable>start</replaceable>
[<replaceable>count</replaceable>]]
by <replaceable>start</replaceable>. First records has offset 0
(unlike the Z39.50 protocol).
</para></listitem></varlistentry>
-
+
<varlistentry><term><literal>quit</literal>
</term>
<listitem><para>
Quits <command>zoomsh</command>.
</para></listitem></varlistentry>
-
+
<varlistentry><term><literal>set</literal>
<replaceable>name</replaceable>
[<replaceable>value</replaceable>]
Sets option <replaceable>name</replaceable> to
<replaceable>value</replaceable>.
</para></listitem></varlistentry>
-
+
<varlistentry><term><literal>get</literal>
<replaceable>name</replaceable>
</term>
<listitem><para>
Prints value of option <replaceable>name</replaceable>.
</para></listitem></varlistentry>
-
+
<varlistentry><term><literal>help</literal>
</term>
<listitem><para>
Prints list of available commands.
</para></listitem></varlistentry>
-
+
</variablelist>
-
+
</refsect1>
<refsect1><title>SEE ALSO</title>
<para>
projects / yaz-moved-to-github.git / commitdiff