No "copy" of source for thread/malloc libraries.

[yaz-moved-to-github.git] / doc / frontend.xml

diff --git a/doc/frontend.xml b/doc/frontend.xml
index 03ee19a..84bb35a 100644 (file)
--- a/doc/frontend.xml
+++ b/doc/frontend.xml
@@ -1,14 +1,12 @@
-<!-- $Id: frontend.xml,v 1.4 2001-07-20 21:34:36 adam Exp $ -->
- <chapter><title id="server">Making an IR Server for Your Database</title>
+<!-- $Id: frontend.xml,v 1.9 2001-11-19 14:06:11 adam 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
   <sect1><title>Introduction</title>
 
    <para>
     If you aren't into documentation, a good way to learn how the

-    backend interface works is to look at the <filename>backend.h</filename>
+    back end interface works is to look at the <filename>backend.h</filename>

     file. Then, look at the small dummy-server in
     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>
     file also makes a good reference, once you've chewed your way through
     the prose of this file.
    </para>

@@ -34,18 +32,18 @@
     <para>
      The backend interface was designed in anticipation of a specific
      integration task, while still attempting to achieve some degree of
     <para>
      The backend interface was designed in anticipation of a specific
      integration task, while still attempting to achieve some degree of

-     generality. We realise fully that there are points where the
+     generality. We realize fully that there are points where the

      interface can be improved significantly. If you have specific
      functions or parameters that you think could be useful, send us a
      mail (or better, sign on to the mailing list referred to in the
      interface can be improved significantly. If you have specific
      functions or parameters that you think could be useful, send us a
      mail (or better, sign on to the mailing list referred to in the

-     toplevel README file). We will try to fit good suggestions into future
+     top-level README file). We will try to fit good suggestions into future

      releases, to the extent that it can be done without requiring
      too many structural changes in existing applications.
     </para>
    </note>
   </sect1>
   
      releases, to the extent that it can be done without requiring
      too many structural changes in existing applications.
     </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>
     We refer to this software as a generic database frontend. Your

@@ -102,22 +100,22 @@
    </para>
 
   </sect1>
    </para>
 
   </sect1>

-  <sect1><title>The Backend API</title>
+  <sect1 id="server.backend"><title>The Backend API</title>

 
    <para>
 
    <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
-    <literal>make</literal> in the toplevel &yaz; directory,
-    everything you need to create your server is put the
-    <filename>lib/libyaz.a</filename> library.
+    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 to link with the
+    <filename>lib/libyaz.la</filename> library.

    </para>
   </sect1>
 
    </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.
 
    <para>
     As mentioned, your <function>main()</function> routine can be quite brief.

@@ -219,8 +217,8 @@ statserv_options_block *statserv_getcontrol(void);
 
      <varlistentry><term>
       <literal>enum oid_proto default_proto;</literal></term>
 
      <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>
      
        Default is <literal>PROTO_Z39_50</literal>.
        </para></listitem></varlistentry>
      

@@ -269,7 +267,7 @@ statserv_options_block *statserv_getcontrol(void);
      <varlistentry><term>
        <literal>void (*bend_stop)(struct statserv_options_block *p)</literal>
       </term>
      <varlistentry><term>
        <literal>void (*bend_stop)(struct statserv_options_block *p)</literal>
       </term>

-      <listitem><para>Pointer to function which is called whenver the server
+      <listitem><para>Pointer to function which is called whenever the server

        has stopped listening for incoming connections. This function pointer
        has a default value of NULL in which case it isn't called.
        When the server operates as an NT service this handler is called
        has stopped listening for incoming connections. This function pointer
        has a default value of NULL in which case it isn't called.
        When the server operates as an NT service this handler is called

@@ -304,7 +302,7 @@ void statserv_setcontrol(statserv_options_block *block);
    </note>
   </sect1>
 
    </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
 
    <para>
     For each service of the protocol, the backend interface declares one or

@@ -412,7 +410,7 @@ typedef struct bend_initresult
    <sect2><title>Search and retrieve</title>
 
     <para>We now describe the handlers that are required to support search -
    <sect2><title>Search and retrieve</title>
 
     <para>We now describe the handlers that are required to support search -

-     and retrieve. You must support two functions - one for seearch - and one
+     and retrieve. You must support two functions - one for search - and one

      for fetch (retrieval of one record). If desirable you can provide a
      third handler which is called when a present request is received which
      allows you to optimize retrieval of multiple-records.
      for fetch (retrieval of one record). If desirable you can provide a
      third handler which is called when a present request is received which
      allows you to optimize retrieval of multiple-records.

@@ -604,7 +602,7 @@ typedef struct {
    <sect2><title>Delete</title>
 
     <para>
    <sect2><title>Delete</title>
 
     <para>

-     For backends that supports delete of a result set only one handler
+     For back-ends that supports delete of a result set only one handler

      must be defined.
     </para>
 
      must be defined.
     </para>
 

@@ -672,7 +670,7 @@ typedef struct bend_scan_rr {
    </sect2>
   </sect1>
 
    </sect2>
   </sect1>
 

-  <sect1><title>Application Invocation</title>
+  <sect1 id="server.invocation"><title>Application Invocation</title>

 
    <para>
     The finished application has the following
 
    <para>
     The finished application has the following

@@ -778,11 +776,11 @@ typedef struct bend_scan_rr {
    <para>
     A listener specification consists of a transport mode followed by a
     colon (:) followed by a listener address. The transport mode is
    <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>
    </para>
 
    <para>

-    For TCP, an address has the form
+    For TCP and SSL, an address has the form

    </para>
 
    <synopsis>
    </para>
 
    <synopsis>

@@ -794,46 +792,19 @@ typedef struct bend_scan_rr {
    </para>
 
    <para>
    </para>
 
    <para>

-    For osi, the address form is
-   </para>
-
-   <synopsis>
-    &lsqb;t-selector /&rsqb; hostname | IP-number &lsqb;: portnumber&rsqb;
-   </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
 
     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 &quot;@&quot; is mapped to
     the address INADDR_ANY, which causes the server to listen on any local
    </screen>
 
    <para>
     In both cases, the special hostname &quot;@&quot; 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.
+    interface. 

    </para>
 
   </sect1>
    </para>
 
   </sect1>

@@ -849,7 +820,7 @@ typedef struct bend_scan_rr {
  sgml-indent-step:1
  sgml-indent-data:t
  sgml-parent-document: "yaz.xml"
  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:
  -->
  sgml-namecase-general:t
  End:
  -->