-<!-- $Id: client.xml,v 1.12 2002-05-30 20:57:38 adam Exp $ -->
+<!-- $Id: client.xml,v 1.13 2002-08-17 07:55:51 adam Exp $ -->
<chapter id="client"><title>The YAZ client</title>
<sect1 id="client.introduction"><title>Introduction</title>
<para>
<para>
It can be started by typing
</para>
- <screen>
- yaz-client [<replaceable>options</replaceable>] [<replaceable>zurl</replaceable>]
- </screen>
+ <cmdsynopsis>
+ <command>yaz-client</command>
+ <arg>-m <replaceable>fname</replaceable></arg>
+ <arg>-a <replaceable>fname</replaceable></arg>
+ <arg>-c <replaceable>fname</replaceable></arg>
+ <arg>-v <replaceable>level</replaceable></arg>
+ <arg>-p <replaceable>target</replaceable></arg>
+ <arg>-u <replaceable>auth</replaceable></arg>
+ <arg>-k <replaceable>size</replaceable></arg>
+ <arg>zurl</arg>
+ </cmdsynopsis>
+
<simpara>
in a UNIX shell / WIN32 console. The <replaceable>zurl</replaceable>,
specifies a Z39.50 host and, if specified, the client first tries to
establish connection with the Z39.50 target on the host.
- Options are, as usual, are prefixed by
- <literal>-</literal> followed by a particular letter.
+ Options are prefixed by <literal>-</literal> followed by a
+ particular letter.
</simpara>
<simpara>
The following options are supported:
<literal>debug</literal>,
<literal>warn</literal>,
<literal>log</literal>,
+ <literal>malloc</literal>,
<literal>all</literal>,
<literal>none</literal>.
</simpara></listitem>
</simpara></listitem>
</varlistentry>
<varlistentry><term>
- <literal>-u</literal> <replaceable>authentication</replaceable>
+ <literal>-u</literal> <replaceable>auth</replaceable>
</term><listitem>
<simpara>Specifies authentication. Usually the form
<replaceable>user</replaceable>/<replaceable>password</replaceable>
</varlistentry>
<varlistentry><term>
- <literal>-k</literal> <replaceable>kilobytes</replaceable>
+ <literal>-k</literal> <replaceable>size</replaceable>
</term><listitem>
<simpara>Specifies the maximum messages size in kilobytes.
The default maximum messages for the YAZ client is 1024
<screen>
yaz-client -a - localhost
</screen>
+ <para>
+ The following command connects to a local server via UNIX
+ socket <filename>/tmp/yaz</filename> and sets maximum message size to
+ 5 MB.
+ </para>
+ <screen>
+ yaz-client -k 5120 unix:/tmp/yaz
+ </screen>
</sect1>
<sect1 id="client.commands"><title>Commands</title>
<para>
Syntax:
</para>
<para>
- [<literal>(tcp|ssl)':'</literal>]<replaceable>host</replaceable>
+ [<literal>(tcp|ssl|unix)':'</literal>]<replaceable>host</replaceable>
[:<replaceable>port</replaceable>][/<replaceable>base></replaceable>]
</para>
</listitem>
-<!-- $Id: comstack.xml,v 1.8 2002-05-22 11:19:20 adam Exp $ -->
+<!-- $Id: comstack.xml,v 1.9 2002-08-17 07:55:51 adam Exp $ -->
<chapter id="comstack"><title>The COMSTACK Module</title>
-
+
<sect1 id="comstack.synopsis"><title>Synopsis (blocking mode)</title>
-
+
<programlisting>
-
+
COMSTACK stack;
char *buf = 0;
int size = 0, length_incoming;
The &comstack;
subsystem provides a transparent interface to different types of transport
stacks for the exchange of BER-encoded data. At present, the
- RFC1729 method (BER over TCP/IP), and an experimental SSL stack
- are supported, but others may be added in time. The philosophy of the
+ RFC1729 method (BER over TCP/IP), local UNIX socket and an
+ experimental SSL stack are supported, but others may be added in time.
+ The philosophy of the
module is to provide a simple interface by hiding unused options and
facilities of the underlying libraries. This is always done at the risk
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 values
- <literal>tcpip_type</literal>
- and
- <literal>ssl_type</literal>
- are recognized. The function returns a null-pointer if a system error
- occurs. The <literal>blocking</literal> parameter should be one if
+ 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)
+ </para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>ssl_type</literal></term>
+ <listitem><para>Secure Socket Layer (SSL). This COMSTACK
+ is experimental and is not fully implemented.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>unix_type</literal></term>
+ <listitem><para>Unix socket (unix only). Fast local transfer via
+ file socket. See <citerefentry><refentrytitle>unix</refentrytitle>
+ <manvolnum>7</manvolnum></citerefentry>.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <function>cs_create</function> function returns a null-pointer
+ if a system error occurs.
+ The <literal>blocking</literal> parameter should be one if
you wish the association to operate in blocking mode, zero otherwise.
The <literal>protocol</literal> field should be
<literal>PROTO_Z3950</literal>.
</synopsis>
<para>
- Receives a PDU from the peer. Returns the number of bytes
- read. In nonblocking mode, it is possible that not all of the packet can be
+ Receives a PDU from the peer. Returns the number of bytes read.
+ In nonblocking mode, it is possible that not all of the packet can be
read at once. In this case, the function returns 1. To simplify the
interface, the function is
responsible for managing the size of the buffer. It will be reallocated
</synopsis>
<para>
- The format for TCP/IP addresses is straightforward:
+ The format for TCP/IP and SSL addresses is:
</para>
<synopsis>
</para>
<para>
- In all transport modes, the special hostname "@" is mapped
- to any local address (the manifest constant <literal>INADDR_ANY</literal>).
+ For TCP/IP and SSL transport modes, the special hostname "@"
+ is mapped to any local address
+ (the manifest constant <literal>INADDR_ANY</literal>).
It is used to establish local listening endpoints in the server role.
</para>
<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>
<function>cs_straddr</function>. The <parameter>str</parameter>
is similar to that described for <function>cs_straddr</function>
but with a prefix denoting the &comstack; type. Prefixes supported
- are <literal>tcp:</literal> and <literal>ssl:</literal> for
- TCP/IP and SSL respectively. If no prefix is given, then TCP/IP
- is used. The <parameter>blocking</parameter> is passed to
+ are <literal>tcp:</literal>, <literal>unix:</literal> and
+ <literal>ssl:</literal> for TCP/IP, UNIX and SSL respectively.
+ If no prefix is given, then TCP/IP is used.
+ The <parameter>blocking</parameter> is passed to
function <function>cs_create</function>. The third parameter
<parameter>vp</parameter> is a pointer to &comstack; stack type
specific values.
For SSL (ssl_type) <parameter>vp</parameter> is an already create
- OpenSSL CTX. For TCP/IP <parameter>vp</parameter> is unused (can be
- set to <literal>NULL</literal>.
+ OpenSSL CTX. For TCP/IP and UNIX <parameter>vp</parameter>
+ is unused (can be set to <literal>NULL</literal>.
</para>
</sect1>
</sect1>
<sect1 id="comstack.summary"><title>Summary and Synopsis</title>
- <synopsis>
- #include <comstack.h>
-
- #include <tcpip.h> /* this is for TCP/IP and SSL support */
+ <synopsis>
+ #include <yaz/comstack.h>
+
+ #include <yaz/tcpip.h> /* this is for TCP/IP and SSL support */
+ #include <yaz/unix.h> /* this is for UNIX sockeL support */
+
COMSTACK cs_create(CS_TYPE type, int blocking, int protocol);
-<!-- $Id: frontend.xml,v 1.12 2002-05-30 20:57:38 adam Exp $ -->
+<!-- $Id: frontend.xml,v 1.13 2002-08-17 07:55:51 adam Exp $ -->
<chapter id="server"><title>Generic server</title>
<sect1><title>Introduction</title>
</para>
<synopsis>
- <replaceable>appname</replaceable> [-szSiTu -a <replaceable>apdufile</replaceable> -l <replaceable>logfile</replaceable> -v <replaceable>loglevel</replaceable> -c <replaceable>config</replaceable>]
+ <replaceable>appname</replaceable> [-szSiT1 -u <replaceable>uid</replaceable> -a <replaceable>apdufile</replaceable> -l <replaceable>logfile</replaceable> -v <replaceable>loglevel</replaceable> -c <replaceable>config</replaceable>]
[listener ...]
</synopsis>
<variablelist>
<varlistentry><term><literal>-a </literal>
- <replaceable>file</replaceable></term>
+ <replaceable>apdufile</replaceable></term>
<listitem><para>
Specify a file for dumping PDUs (for diagnostic purposes).
The special name "-" sends output to
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
<replaceable>level</replaceable></term>
<listitem><para>
The log level. Use a comma-separated list of members of the set
- {fatal,debug,warn,log,all,none}.
+ {fatal,debug,warn,log,malloc,all,none}.
</para></listitem></varlistentry>
<varlistentry><term><literal>-u </literal>
- <replaceable>userid</replaceable></term>
+ <replaceable>uid</replaceable></term>
<listitem><para>
Set user ID. Sets the real UID of the server process to that of the
given user. It's useful if you aren't comfortable with having the
<varlistentry><term><literal>-w </literal>
<replaceable>dir</replaceable></term>
<listitem><para>
- Working directory.
+ 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>).
</para></listitem></varlistentry>
<varlistentry><term><literal>-i</literal></term>
<varlistentry><term><literal>-install</literal></term>
<listitem><para>
- Use this to install the server as an NT service (Windows 2000/NT only).
+ Use this to install the server as an NT service
+ (Windows 2000/NT 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 2000/NT only).
+ Use this to remove the server from the NT services
+ (Windows 2000/NT 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>
+ <replaceable>size</replaceable></term>
<listitem><para>
Maximum record size/message size, in kilobytes.
</para></listitem></varlistentry>
-
+
</variablelist>
</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> or <literal>ssl</literal>.
+ either <literal>tcp</literal>, <literal>unix:</literal> or
+ <literal>ssl</literal>.
</para>
-
+
<para>
For TCP and SSL, an address has the form
</para>
</para>
<para>
+ For UNIX local socket the address is the name local file.
+ </para>
+
+ <para>
Examples
</para>
tcp:dranet.dra.com
ssl:ssl.enterprise.com:3000
+
+ unix:/tmp/yaz
</screen>
<para>
- In both cases, the special hostname "@" is mapped to
+ For TCP/IP and SSL, the special hostname "@" is mapped to
the address <literal>INADDR_ANY</literal>, which causes the
server to listen on any local interface.
</para>
-<!-- $Id: installation.xml,v 1.11 2002-05-22 11:19:20 adam Exp $ -->
+<!-- $Id: installation.xml,v 1.12 2002-08-17 07:55:51 adam Exp $ -->
<chapter id="installation"><title>Compilation and Installation</title>
<sect1><title>Introduction</title>
<listitem><para>HP/UX</para></listitem>
<listitem><para>SunOS/Solaris</para></listitem>
<listitem><para>DEC Unix</para></listitem>
- <listitem><para>OpenBSD/FreeBSD</para></listitem>
+ <listitem><para>BSDs: FreeBSD, OpenBSD, NetBSD, MAC OSX
+ </para></listitem>
<listitem><para>Linux</para></listitem>
<listitem><para>IBM AIX</para></listitem>
<listitem><para>Data General DG/UX (with some CFLAGS tinkering)
let us know about it. If you run into difficulties, we will try to help
if we can, and if you solve the problems, we would be happy to include
your fixes in the next release. So far, we have mostly avoided
- #ifdefs for individual platforms, and we'd like to keep it that
- way as far as it makes sense.
+ <literal>#ifdefs</literal> for individual platforms, and we'd
+ like to keep it that way as far as it makes sense.
</para>
<para>
bug-fixes, as well as general discussion. Subscribe by sending mail to
<ulink url="mailto:yaz-request@indexdata.dk">
yaz-request@indexdata.dk
- </ulink>.
+ </ulink> or fill-in the form
+ <ulink url="http://www.indexdata.dk/mailman/listinfo/yazlist">
+ here</ulink>.
General questions and problems can be directed at
<ulink url="mailto:yaz-help@indexdata.dk">
yaz-help@indexdata.dk
<para>
Note that if your system doesn't have a native ANSI C compiler, you may
have to acquire one separately. We recommend
- <ulink url="http://gcc.gnu.org">GCC</ulink>.
+ <ulink url="http://gcc.gnu.org/">GCC</ulink>.
</para>
<para>
For UNIX, the GNU tools
<ulink url="http://www.gnu.org/software/autoconf/">Autoconf</ulink>,
<ulink url="http://www.gnu.org/software/automake/">Automake</ulink> and
<ulink url="http://www.gnu.org/software/libtool/">Libtool</ulink>
- is used to generate Makefiles and configure &yaz; for the system.
+ are used to generate Makefiles and configure &yaz; for the system.
You do <emphasis>not</emphasis> these tools unless you're using the
CVS version of &yaz;.
Generally it should be sufficient to run configure without options,
-<!-- $Id: introduction.xml,v 1.7 2001-10-26 20:13:44 adam Exp $ -->
+<!-- $Id: introduction.xml,v 1.8 2002-08-17 07:55:51 adam Exp $ -->
<chapter id="introduction"><title>Introduction</title>
<para>
specification of the protocol (generally Z39.50-1995). In the case of
base types (those originating in the ASN.1 standard itself), the prefix
<literal>Odr_</literal> is sometimes seen. Either way, look for
- the actual definition in either <filename>proto.h</filename> (for the types
+ the actual definition in either <filename>z-core.h</filename> (for the types
from the protocol), <filename>odr.h</filename> (for the primitive ASN.1
- types, or <filename>odr_use.h</filename> (for the ASN.1
- <emphasis>useful</emphasis> types). The &asn; library also
- provides functions (which are, in turn, defined using &odr;
- primitives) for encoding and decoding data values. Their general form is
+ types).
+ The &asn; library also provides functions (which are, in turn,
+ defined using &odr; primitives) for encoding and decoding data values.
+ Their general form is
- <synopsis>
- int z_xxx(ODR o, Z_xxx **p, int optional, const char *name);
- </synopsis>
+ <funcsynopsis>
+ <funcprototype><funcdef>int <function>z_<replaceable>xxx</replaceable></function></funcdef>
+ <paramdef>ODR <parameter>o</parameter></paramdef>
+ <paramdef>Z_<replaceable>xxx</replaceable> **<parameter>p</parameter></paramdef>
+ <paramdef>int <parameter>optional</parameter></paramdef>
+ <paramdef>const char *<parameter>name</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
(note the lower-case "z" in the function name)
</para>
(passively or actively, depending on the role of your application),
and for exchanging BER-encoded PDUs over that connection. When you
create a connection endpoint, you need to specify what transport to
- use (TCP/IP or SSL).
+ use (TCP/IP, SSL or UNIX sockets).
For the remainder of the connection's lifetime, you don't have
to worry about the underlying transport protocol at all - the &comstack;
will ensure that the correct mechanism is used.
can use SNACC or BERUtils instead, and still have the benefits of the
transparent transport approach of the &comstack; module. Secondly,
we realize that you may have to fit the toolkit into an existing
- event-processing structure, in a way that
- is incompatible with the &comstack; interface or some other part of &yaz;.
+ event-processing structure, in a way that is incompatible with
+ the &comstack; interface or some other part of &yaz;.
</para>
</chapter>
projects / yaz-moved-to-github.git / commitdiff