Update doc WRT @4, @6, @ notations

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

diff --git a/doc/server.xml b/doc/server.xml
index 02557e2..f5b28f4 100644 (file)
--- a/doc/server.xml
+++ b/doc/server.xml
@@ -1,6 +1,6 @@
  <chapter id="server"><title>Generic server</title>
   <sect1 id="server.introduction"><title>Introduction</title>
  <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>
     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>

@@ -47,7 +47,7 @@
      </para>
    </note>
   </sect1>
      </para>
    </note>
   </sect1>

-  
+

   <sect1 id="server.frontend"><title>The Database Frontend</title>
 
    <para>
   <sect1 id="server.frontend"><title>The Database Frontend</title>
 
    <para>

@@ -89,7 +89,7 @@
     <listitem><para>
       Extended Services (optional).
      </para></listitem>
     <listitem><para>
       Extended Services (optional).
      </para></listitem>

-    
+

     <listitem><para>
       Result-Set Delete (optional).
      </para></listitem>
     <listitem><para>
       Result-Set Delete (optional).
      </para></listitem>

@@ -97,11 +97,11 @@
     <listitem><para>
       Result-Set Sort (optional).
      </para></listitem>
     <listitem><para>
       Result-Set Sort (optional).
      </para></listitem>

-    
+

     <listitem><para>
       Return Explain for SRU (optional).
      </para></listitem>
     <listitem><para>
       Return Explain for SRU (optional).
      </para></listitem>

-    
+

    </itemizedlist>
 
    <para>
    </itemizedlist>
 
    <para>

@@ -157,9 +157,9 @@ int statserv_main(int argc, char **argv,
     connection.
     If you do use global variables and forking, you should be aware, then,
     that these cannot be shared between associations, unless you explicitly
     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>

-   
+

    <para>
     The server provides a mechanism for controlling some of its behavior
     without using command-line options. The function
    <para>
     The server provides a mechanism for controlling some of its behavior
     without using command-line options. The function

@@ -173,7 +173,7 @@ int statserv_main(int argc, char **argv,
     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:
     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>
     <variablelist>
      <varlistentry><term>
        <literal>int dynamic</literal></term><listitem><para>

@@ -182,7 +182,7 @@ int statserv_main(int argc, char **argv,
        TRUE. This flag is only read by UNIX-based servers (WIN32 based servers
        doesn't fork).
        </para></listitem></varlistentry>
        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
      <varlistentry><term>
        <literal>int threads</literal></term><listitem><para>
        A boolean value, which determines whether the server

@@ -191,18 +191,18 @@ int statserv_main(int argc, char **argv,
        that offer POSIX Threads support.
        WIN32-based servers always operate in threaded mode.
        </para></listitem></varlistentry>
        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>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 (&quot;&quot;: stderr).
        </para></listitem></varlistentry>
      <varlistentry><term>
        <literal>char logfile[ODR_MAXNAME+1]</literal></term>
       <listitem><para>File for diagnostic output (&quot;&quot;: stderr).
        </para></listitem></varlistentry>

-     
+

      <varlistentry><term>
        <literal>char apdufile[ODR_MAXNAME+1]</literal></term>
       <listitem><para>
      <varlistentry><term>
        <literal>char apdufile[ODR_MAXNAME+1]</literal></term>
       <listitem><para>

@@ -225,13 +225,13 @@ int statserv_main(int argc, char **argv,
        <literal>PROTO_SR</literal>.
        Default is <literal>PROTO_Z39_50</literal>.
        </para></listitem></varlistentry>
        <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 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
      <varlistentry><term>
        <literal>int maxrecordsize;</literal></term>
       <listitem><para>Maximum permissible record (message) size. Default

@@ -252,7 +252,7 @@ int statserv_main(int argc, char **argv,
       <listitem><para>Set user id to the user specified, after binding
        the listener addresses.
        </para></listitem></varlistentry>
       <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>
      <varlistentry><term>
        <literal>void (*bend_start)(struct statserv_options_block *p)</literal>
       </term>

@@ -265,9 +265,9 @@ int statserv_main(int argc, char **argv,
        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
        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>
        </para></listitem></varlistentry>

-     
+

      <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>

@@ -293,7 +293,7 @@ int statserv_main(int argc, char **argv,
     a static area. You are allowed to change the contents of the structure,
     but the changes will not take effect before you call
    </para>
     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>
    <synopsis>
 void statserv_setcontrol(statserv_options_block *block);
    </synopsis>

@@ -348,35 +348,35 @@ bend_initresult (*bend_init)(bend_initrequest *r);
 typedef struct bend_initrequest
 {
     /** \brief user/name/password to be read */
 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) */
     /** \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 */
     /** \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;
 
     */
     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 */
     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).
     */
     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).
     */

@@ -448,7 +448,7 @@ typedef struct bend_initresult
     <para>
      The <literal>auth</literal> member holds the authentication information
      part of the Z39.50 Initialize Request. Interpret this if your serves
     <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>
     </para>
 
     <para>

@@ -556,7 +556,7 @@ typedef struct {
      For SRU operation, a Bib-1 diagnostic code is mapped to
      SRU diagnostic.
     </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);
 
     <synopsis>
 int (*bend_fetch) (void *handle, bend_fetch_rr *rr);
 

@@ -686,7 +686,7 @@ typedef struct {
     <para>
      Note that this is handler serves as a supplement for
      <function>bend_fetch</function> and need not to be defined in order to
     <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>
     </para>
 
    </sect2>

@@ -709,7 +709,7 @@ typedef struct bend_delete_rr {
     int delete_status;      /* status for the whole operation */
     int *statuses;          /* status each set - indexed as setnames */
     ODR stream;
     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_delete_rr;
     </synopsis>
 

@@ -764,9 +764,9 @@ typedef struct bend_scan_rr {
 } bend_scan_rr;
     </synopsis>
    <para>
 } 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>
     <literal>scanClause</literal>.
    </para>
    <note>

@@ -786,21 +786,21 @@ typedef struct bend_scan_rr {
    </para>
 
    &gfs-synopsis;
    </para>
 
    &gfs-synopsis;

-   
+

    <para>
     The options are:
 
     &gfs-options;
 
    </para>
    <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>
     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>
    <para>
     For TCP and SSL, an address has the form
    </para>

@@ -808,7 +808,7 @@ typedef struct bend_scan_rr {
    <synopsis>
     hostname | IP-number [: portnumber]
    </synopsis>
    <synopsis>
     hostname | IP-number [: portnumber]
    </synopsis>

-   
+

    <para>
     The port number defaults to 210 (standard Z39.50 port).
    </para>
    <para>
     The port number defaults to 210 (standard Z39.50 port).
    </para>

@@ -818,11 +818,13 @@ typedef struct bend_scan_rr {
    </para>
 
    <para>
    </para>
 
    <para>

-    For TCP/IP and SSL, the special hostnames <literal>@</literal> and
-    <literal>@6</literal> are mapped to the addresses 
-    <literal>INADDR_ANY</literal> (IPV4) and
-    <literal>IN6ADDR_ANY_INIT</literal> (IPV6)
-    respectively. 
+    For TCP/IP and SSL, the special hostnames <literal>@</literal>,
+    maps to <literal>IN6ADDR_ANY_INIT</literal> with
+    IPV4 binding as well (bindv6only=0),
+    The special hostname <literal>@4</literal> binds to
+    <literal>INADDR_ANY</literal> (IPV4 only listener).
+    The special hostname <literal>@6</literal> binds to
+    <literal>IN6ADDR_ANY_INIT</literal> with bindv6only=1 (IPV6 only listener).

    </para>
 
    <example id="server.example.running.unix"><title>Running the GFS on Unix</title>
    </para>
 
    <example id="server.example.running.unix"><title>Running the GFS on Unix</title>

@@ -845,7 +847,7 @@ typedef struct bend_scan_rr {
      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;">
      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
      directive.
      If you have virtual host
      <literal>srw.mydomain</literal> you can use the following directives

@@ -878,7 +880,7 @@ typedef struct bend_scan_rr {
    &gfs-virtual;
   </sect1>
  </chapter>
    &gfs-virtual;
   </sect1>
  </chapter>

- 
+

  <!-- Keep this comment at the end of the file
  Local variables:
  mode: sgml
  <!-- Keep this comment at the end of the file
  Local variables:
  mode: sgml