-<!-- $Id: frontend.xml,v 1.5 2001-08-13 09:42:54 adam Exp $ -->
- <chapter><title id="server">Making an IR Server for Your Database</title>
+<!-- $Id: frontend.xml,v 1.11 2002-03-05 12:45:48 mike Exp $ -->
+ <chapter id="server"><title>Generic server</title>
<sect1><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>
file. Then, look at the small dummy-server in
- <filename>ztest/ztest.c</filename>. Finally, you can have a look at
- the <filename>seshigh.c</filename> file, which is where most of the
- logic of the frontend server is located. The <filename>backend.h</filename>
+ <filename>ztest/ztest.c</filename>. The <filename>backend.h</filename>
file also makes a good reference, once you've chewed your way through
the prose of this file.
</para>
</note>
</sect1>
- <sect1><title>The Database Frontend</title>
+ <sect1 id="server.frontend"><title>The Database Frontend</title>
<para>
We refer to this software as a generic database frontend. Your
</para>
</sect1>
- <sect1><title>The Backend API</title>
+ <sect1 id="server.backend"><title>The Backend API</title>
<para>
- The headers files that you need to use the interface are in the
- <filename>include/yaz</filename> directory. They are called
- <filename>statserv.h</filename> and <filename>backend.h</filename>. They
- will include other files from the <filename>include/yaz</filename>
- directory, so you'll probably want to use the -I option of your
- compiler to tell it where to find the files. When you run
+ The header file that you need to use the interface are in the
+ <filename>include/yaz</filename> directory. It's called
+ <filename>backend.h</filename>. It will include other files from
+ the <filename>include/yaz</filename> directory, so you'll
+ probably want to use the -I option of your compiler to tell it
+ where to find the files. When you run
<literal>make</literal> in the top-level &yaz; directory,
- everything you need to create your server is put the
- <filename>lib/libyaz.a</filename> library.
+ everything you need to create your server is to link with the
+ <filename>lib/libyaz.la</filename> library.
</para>
</sect1>
- <sect1><title>Your main() Routine</title>
+ <sect1 id="server.main"><title>Your main() Routine</title>
<para>
As mentioned, your <function>main()</function> routine can be quite brief.
<varlistentry><term>
<literal>enum oid_proto default_proto;</literal></term>
- <listitem><para>Either <literal>PROTO_SR</literal> or
- <literal>PROTO_Z3950</literal>.
+ <listitem><para>Either <literal>PROTO_Z3950</literal> or
+ <literal>PROTO_SR</literal>.
Default is <literal>PROTO_Z39_50</literal>.
</para></listitem></varlistentry>
</note>
</sect1>
- <sect1><title>The Backend Functions</title>
+ <sect1 id="server.backendfunctions"><title>The Backend Functions</title>
<para>
For each service of the protocol, the backend interface declares one or
Z_ReferenceId *referenceId;/* reference ID */
char *peer_name; /* dns host of peer (client) */
+ char *implementation_id;
char *implementation_name;
char *implementation_version;
int (*bend_sort) (void *handle, bend_sort_rr *rr);
<para>
The members <literal>peer_name</literal>,
+ <literal>implementation_id</literal>,
<literal>implementation_name</literal> and
- <literal>implementation_version</literal> holds DNS of client, name
+ <literal>implementation_version</literal> holds DNS of client, ID of implementor, name
of client (Z39.50) implementation - and version.
</para>
</sect2>
</sect1>
- <sect1><title>Application Invocation</title>
+ <sect1 id="server.invocation"><title>Application Invocation</title>
<para>
The finished application has the following
<variablelist>
- <varlistentry><term>-a <replaceable>file</replaceable></term>
+ <varlistentry><term><literal>-a </literal>
+ <replaceable>file</replaceable></term>
<listitem><para>
Specify a file for dumping PDUs (for diagnostic purposes).
The special name "-" sends output to
<literal>stderr</literal>.
</para></listitem></varlistentry>
- <varlistentry><term>-S</term>
+ <varlistentry><term><literal>-S</literal></term>
<listitem><para>
Don't fork or make threads on connection requests. This is good for
debugging, but not recommended for real operation: Although the
current users.
</para></listitem></varlistentry>
- <varlistentry><term>-T</term>
+ <varlistentry><term><literal>-T</literal></term>
<listitem><para>
Operate the server in threaded mode. The server creates a thread
for each connection rather than a fork a process. Only available
on UNIX systems that offers POSIX threads.
</para></listitem></varlistentry>
- <varlistentry><term>-s</term>
+ <varlistentry><term><literal>-s</literal></term>
<listitem><para>
Use the SR protocol (obsolete).
</para></listitem></varlistentry>
- <varlistentry><term>-z</term>
+ <varlistentry><term><literal>-z</literal></term>
<listitem><para>
Use the Z39.50 protocol (default). These two options complement
each other. You can use both multiple times on the same command
concurrently, on different local ports.
</para></listitem></varlistentry>
- <varlistentry><term>-l <replaceable>file</replaceable></term>
+ <varlistentry><term><literal>-l </literal>
+ <replaceable>file</replaceable></term>
<listitem><para>The logfile.
</para></listitem></varlistentry>
- <varlistentry><term>-c <replaceable>config</replaceable></term>
+ <varlistentry><term><literal>-c </literal>
+ <replaceable>config</replaceable></term>
<listitem><para>A user option that serves as a specifier for some
sort of configuration, e.g. a filename.
The argument to this option is transferred to member
<literal>statserv_options_block</literal>.
</para></listitem></varlistentry>
- <varlistentry><term>-v <replaceable>level</replaceable></term>
+ <varlistentry><term><literal>-v </literal>
+ <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}.
</para></listitem></varlistentry>
- <varlistentry><term>-u <replaceable>userid</replaceable></term>
+ <varlistentry><term><literal>-u </literal>
+ <replaceable>userid</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
privileged port.
</para></listitem></varlistentry>
- <varlistentry><term>-w <replaceable>dir</replaceable></term>
+ <varlistentry><term><literal>-w </literal>
+ <replaceable>dir</replaceable></term>
<listitem><para>
Working directory.
</para></listitem></varlistentry>
- <varlistentry><term>-i</term>
+ <varlistentry><term><literal>-i</literal></term>
<listitem><para>
- Use this when running from the <application>inetd</application> server.
+ Use this to make the the server run from the
+ <application>inetd</application> server (UNIX only).
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><literal>-install</literal></term>
+ <listitem><para>
+ 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).
</para></listitem></varlistentry>
- <varlistentry><term>-t <replaceable>minutes</replaceable></term>
+ <varlistentry><term><literal>-t </literal>
+ <replaceable>minutes</replaceable></term>
<listitem><para>
Idle session timeout, in minutes.
</para></listitem></varlistentry>
- <varlistentry><term>-k <replaceable>size</replaceable></term>
+ <varlistentry><term><literal>-k </literal>
+ <replaceable>size</replaceable></term>
<listitem><para>
Maximum record size/message size, in kilobytes.
</para></listitem></varlistentry>
<para>
A listener specification consists of a transport mode followed by a
colon (:) followed by a listener address. The transport mode is
- either <literal>osi</literal> or <literal>tcp</literal>.
+ either <literal>tcp</literal> or <literal>ssl</literal>.
</para>
<para>
- For TCP, an address has the form
+ For TCP and SSL, an address has the form
</para>
<synopsis>
</para>
<para>
- For osi, the address form is
- </para>
-
- <synopsis>
- [t-selector /] hostname | IP-number [: portnumber]
- </synopsis>
-
- <para>
- The transport selector is given as a string of hex digits (with an even
- number of digits). The default port number is 102 (RFC1006 port).
- </para>
-
- <para>
Examples
</para>
<screen>
tcp:dranet.dra.com
- osi:0402/dbserver.osiworld.com:3000
+ ssl:ssl.enterprise.com:3000
</screen>
<para>
In both cases, the special hostname "@" is mapped to
- the address INADDR_ANY, which causes the server to listen on any local
- interface. To start the server listening on the registered ports for
- Z39.50 and SR over OSI/RFC1006, and to drop root privileges once the
- ports are bound, execute the server like this (from a root shell):
- </para>
-
- <screen>
- my-server -u daemon tcp:@ -s osi:@
- </screen>
-
- <para>
- You can replace <literal>daemon</literal> with another user, eg. your
- own account, or a dedicated IR server account.
- <literal>my-server</literal> should be the name of your
- server application. You can test the procedure with the
- <application>yaz-ztest</application> application.
+ the address <literal>INADDR_ANY</literal>, which causes the
+ server to listen on any local interface.
</para>
</sect1>
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document: "yaz.xml"
- sgml-local-catalogs: "../../docbook/docbook.cat"
+ sgml-local-catalogs: nil
sgml-namecase-general:t
End:
-->
projects / yaz-moved-to-github.git / blobdiff