Use ZOOM_API(int) for public function ZOOM_connection_is_idle

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

diff --git a/doc/frontend.xml b/doc/frontend.xml
index a455153..0f83a6e 100644 (file)
--- a/doc/frontend.xml
+++ b/doc/frontend.xml
@@ -1,6 +1,6 @@
-<!-- $Id: frontend.xml,v 1.18 2003-11-03 10:46:52 adam Exp $ -->
+<!-- $Id: frontend.xml,v 1.32 2006-10-05 08:26:58 adam Exp $ -->

  <chapter id="server"><title>Generic server</title>
  <chapter id="server"><title>Generic server</title>

-  <sect1><title>Introduction</title>
+  <sect1 id="server.introduction"><title>Introduction</title>

    
    <para>
     If you aren't into documentation, a good way to learn how the
    
    <para>
     If you aren't into documentation, a good way to learn how the

@@ -13,7 +13,7 @@
 
    <para>
     If you have a database system that you would like to make available by
 
    <para>
     If you have a database system that you would like to make available by

-    means of Z39.50, SRW o SRU, &yaz; basically offers your two options. You
+    means of Z39.50 or SRU, &yaz; basically offers your two options. You

     can use the APIs provided by the &asn;, &odr;, and &comstack;
     modules to
     create and decode PDUs, and exchange them with a client.
     can use the APIs provided by the &asn;, &odr;, and &comstack;
     modules to
     create and decode PDUs, and exchange them with a client.

@@ -99,6 +99,10 @@
       Result-Set Sort (optional).
      </para></listitem>
     
       Result-Set Sort (optional).
      </para></listitem>
     

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

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

@@ -163,7 +167,7 @@ int statserv_main(int argc, char **argv,
    </para>
 
    <synopsis>
    </para>
 
    <synopsis>

-statserv_options_block *statserv_getcontrol(void);
+    statserv_options_block *statserv_getcontrol(void);

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

@@ -196,12 +200,6 @@ statserv_options_block *statserv_getcontrol(void);
        </para></listitem></varlistentry>
      
      <varlistentry><term>
        </para></listitem></varlistentry>
      
      <varlistentry><term>

-       <literal>int loglevel</literal></term><listitem><para>
-       Set this by ORing the constants defined in
-       <filename>include/yaz/yaz-log.h</filename>.
-       </para></listitem></varlistentry>
-     
-     <varlistentry><term>

        <literal>char logfile&lsqb;ODR_MAXNAME+1&rsqb;</literal></term>
       <listitem><para>File for diagnostic output (&quot;&quot;: stderr).
        </para></listitem></varlistentry>
        <literal>char logfile&lsqb;ODR_MAXNAME+1&rsqb;</literal></term>
       <listitem><para>File for diagnostic output (&quot;&quot;: stderr).
        </para></listitem></varlistentry>

@@ -232,7 +230,7 @@ statserv_options_block *statserv_getcontrol(void);
      <varlistentry><term>
        <literal>int idle_timeout;</literal></term>
       <listitem><para>Maximum session idle-time, in minutes. Zero indicates
      <varlistentry><term>
        <literal>int idle_timeout;</literal></term>
       <listitem><para>Maximum session idle-time, in minutes. Zero indicates

-       no (infinite) timeout. Default is 120 minutes.
+       no (infinite) timeout. Default is 15 minutes.

        </para></listitem></varlistentry>
      
      <varlistentry><term>
        </para></listitem></varlistentry>
      
      <varlistentry><term>

@@ -317,7 +315,7 @@ void statserv_setcontrol(statserv_options_block *block);
     functions representing the services that you wish to implement.
    </para>
 
     functions representing the services that you wish to implement.
    </para>
 

-   <sect2><title>Init</title>
+   <sect2 id="server.init"><title>Init</title>

 
     <synopsis>
 bend_initresult (*bend_init)(bend_initrequest *r);
 
     <synopsis>
 bend_initresult (*bend_init)(bend_initrequest *r);

@@ -332,8 +330,8 @@ bend_initresult (*bend_init)(bend_initrequest *r);
     </para>
 
     <para>
     </para>
 
     <para>

-     This handler is also called when operating in SRW/SRU mode - when
-     a connection has been made (even though SRW/SRU does not offer
+     This handler is also called when operating in SRU mode - when
+     a connection has been made (even though SRU does not offer

      this service).
     </para>
 
      this service).
     </para>
 

@@ -372,6 +370,8 @@ typedef struct bend_initrequest
     /* character set and language negotiation - see include/yaz/z-charneg.h */
     Z_CharSetandLanguageNegotiation *charneg_request;
     Z_External *charneg_response;
     /* character set and language negotiation - see include/yaz/z-charneg.h */
     Z_CharSetandLanguageNegotiation *charneg_request;
     Z_External *charneg_response;

+    int (*bend_srw_explain)(void *handle, bend_explain_rr *rr);
+    int (*bend_srw_scan)(void *handle, bend_scan_rr *rr);

 } bend_initrequest;
 
 typedef struct bend_initresult
 } bend_initrequest;
 
 typedef struct bend_initresult

@@ -429,7 +429,7 @@ typedef struct bend_initresult
 
    </sect2>
 
 
    </sect2>
 

-   <sect2><title>Search and retrieve</title>
+   <sect2 id="server.search.retrieve"><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 search - and one
 
     <para>We now describe the handlers that are required to support search -
      and retrieve. You must support two functions - one for search - and one

@@ -458,6 +458,7 @@ typedef struct {
     int hits;                  /* number of hits */
     int errcode;               /* 0==OK */
     char *errstring;           /* system error string or NULL */
     int hits;                  /* number of hits */
     int errcode;               /* 0==OK */
     char *errstring;           /* system error string or NULL */

+    Z_OtherInformation *search_info;

 } bend_search_rr;
     </synopsis>
 
 } bend_search_rr;
     </synopsis>
 

@@ -496,20 +497,20 @@ typedef struct {
 
     <para>
      The <function>bend_search</function> handler is also called when
 
     <para>
      The <function>bend_search</function> handler is also called when

-     the frontend server receives a SRW/SRU SearchRetrieveRequest.
-     For SRW/SRU, a CQL query is usually provided by the client.
+     the frontend server receives a SRU SearchRetrieveRequest.
+     For SRU, a CQL query is usually provided by the client.

      The CQL query is available as part of <literal>Z_Query</literal>
      structure (note that CQL is now part of Z39.50 via an external).
      To support CQL in existing implementations that only do Type-1,
      we refer to the CQL-to-PQF tool described
      The CQL query is available as part of <literal>Z_Query</literal>
      structure (note that CQL is now part of Z39.50 via an external).
      To support CQL in existing implementations that only do Type-1,
      we refer to the CQL-to-PQF tool described

-     <link linkend="tools.cql.pqf">here</link>.
+     <link linkend="cql.to.pqf">here</link>.

     </para>
 
     <para>
      To maintain backwards compatibility, the frontend server
      of yaz always assume that error codes are BIB-1 diagnostics.
     </para>
 
     <para>
      To maintain backwards compatibility, the frontend server
      of yaz always assume that error codes are BIB-1 diagnostics.

-     For SRW/SRU operation, a Bib-1 diagnostic code is mapped to
-     SRW/SRU diagnostic.
+     For SRU operation, a Bib-1 diagnostic code is mapped to
+     SRU diagnostic.

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

@@ -541,15 +542,15 @@ typedef struct bend_fetch_rr {
     <para>
      The frontend server calls the <function>bend_fetch</function> handler
      when it needs database records to fulfill a Z39.50 Search Request, a
     <para>
      The frontend server calls the <function>bend_fetch</function> handler
      when it needs database records to fulfill a Z39.50 Search Request, a

-     Z39.50 Present Request or a SRW SearchRetrieveRequest.
+     Z39.50 Present Request or a SRU SearchRetrieveRequest.

      The <literal>setname</literal> is simply the name of the result set
      that holds the reference to the desired record.
      The <literal>number</literal> is the offset into the set (with 1
      being the first record in the set). The <literal>format</literal> field
      The <literal>setname</literal> is simply the name of the result set
      that holds the reference to the desired record.
      The <literal>number</literal> is the offset into the set (with 1
      being the first record in the set). The <literal>format</literal> field

-     is the record format requested by the client (See section
-     <link linkend="oid">Object Identifiers</link>). The value
-     <literal>VAL_NONE</literal> indicates that the client did not
-     request a specific format. The <literal>stream</literal> argument
+     is the record format requested by the client (See
+     <xref linkend="asn.oid"/>).
+     The value <literal>VAL_NONE</literal> indicates that the client did
+     not request a specific format. The <literal>stream</literal> argument

      is an &odr; stream which should be used for
      allocating space for structured data records.
      The stream will be reset when all records have been assembled, and
      is an &odr; stream which should be used for
      allocating space for structured data records.
      The stream will be reset when all records have been assembled, and

@@ -559,11 +560,11 @@ typedef struct bend_fetch_rr {
     </para>
 
     <para>
     </para>
 
     <para>

-     If a SRW/SRU SearchRetrieveRequest is received by the frontend server,
+     If a SRU SearchRetrieveRequest is received by the frontend server,

      the <literal>referenceId</literal> is NULL and the
      <literal>request_format</literal> (transfer syntax) is XML (OID name 
      <literal>VAL_TEXT_XML</literal>).
      the <literal>referenceId</literal> is NULL and the
      <literal>request_format</literal> (transfer syntax) is XML (OID name 
      <literal>VAL_TEXT_XML</literal>).

-     The schema for SRW/SRU is stored in both the
+     The schema for SRU is stored in both the

      <literal>Z_RecordComposition</literal>
      structure and <literal>schema</literal> (simple string).
     </para>
      <literal>Z_RecordComposition</literal>
      structure and <literal>schema</literal> (simple string).
     </para>

@@ -649,7 +650,7 @@ typedef struct {
 
    </sect2>
 
 
    </sect2>
 

-   <sect2><title>Delete</title>
+   <sect2 id="server.delete"><title>Delete</title>

 
     <para>
      For back-ends that supports delete of a result set only one handler
 
     <para>
      For back-ends that supports delete of a result set only one handler

@@ -683,7 +684,7 @@ typedef struct bend_delete_rr {
 
    </sect2>
 
 
    </sect2>
 

-   <sect2><title>scan</title>
+   <sect2 id="server.scan"><title>Scan</title>

 
     <para>
      For servers that wish to offer the scan service one handler
 
     <para>
      For servers that wish to offer the scan service one handler

@@ -715,8 +716,21 @@ typedef struct bend_scan_rr {
     bend_scan_status status;
     int errcode;
     char *errstring;
     bend_scan_status status;
     int errcode;
     char *errstring;

+    char *scanClause;   /* CQL scan clause */

 } bend_scan_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 
+    <literal>scanClause</literal>.
+   </para>
+   <note>
+    <para>
+     if designed today, it would be a choice using a union or similar,
+     but that would break binary compatibility with existing servers.
+    </para>
+    </note>

    </sect2>
   </sect1>
 
    </sect2>
   </sect1>
 

@@ -726,27 +740,13 @@ typedef struct bend_scan_rr {
     The finished application has the following
     invocation syntax (by way of <function>statserv_main()</function>):
    </para>
     The finished application has the following
     invocation syntax (by way of <function>statserv_main()</function>):
    </para>

-   
-   <cmdsynopsis>
-    <command>appname</command>
-    <arg choice="opt"><option>-a <replaceable>file</replaceable></option></arg>
-    <arg choice="opt"><option>-v <replaceable>level</replaceable></option></arg>
-    <arg choice="opt"><option>-l <replaceable>file</replaceable></option></arg>
-    <arg choice="opt"><option>-u <replaceable>uid</replaceable></option></arg>
-    <arg choice="opt"><option>-c <replaceable>config</replaceable></option></arg>
-    <arg choice="opt"><option>-t <replaceable>minutes</replaceable></option></arg>
-    <sbr/>
-    <arg choice="opt"><option>-k <replaceable>kilobytes</replaceable></option></arg>
-    <arg choice="opt"><option>-d <replaceable>daemon</replaceable></option></arg>
-    <arg choice="opt"><option>-w <replaceable>dir</replaceable></option></arg>
-    <arg choice="opt"><option>-ziST1</option></arg>
-    <arg choice="opt" rep="repeat">listener-spec</arg>
-   </cmdsynopsis>
+
+   &gfs-synopsis;

    
    <para>
     The options are:
 
    
    <para>
     The options are:
 

-    &ztest-options;
+    &gfs-options;

 
    </para>
    
 
    </para>
    

@@ -764,7 +764,7 @@ typedef struct bend_scan_rr {
    <synopsis>
     hostname | IP-number &lsqb;: portnumber&rsqb;
    </synopsis>
    <synopsis>
     hostname | IP-number &lsqb;: portnumber&rsqb;
    </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>

@@ -779,7 +779,7 @@ typedef struct bend_scan_rr {
     which causes the server to listen on any local interface. 
    </para>
 
     which causes the server to listen on any local interface. 
    </para>
 

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

     <para>
      Assuming the server application <replaceable>appname</replaceable> is
      started as root, the following will make it listen on port 210.
     <para>
      Assuming the server application <replaceable>appname</replaceable> is
      started as root, the following will make it listen on port 210.

@@ -790,16 +790,15 @@ typedef struct bend_scan_rr {
      </screen>
     </para>
     <para>
      </screen>
     </para>
     <para>

-     The server will accept Z39.50 requests and offer SRW/SRU service
-     on port 210.
+     The server will accept Z39.50 requests and offer SRU service on port 210.

     </para>
    </example>
     </para>
    </example>

-   <example><title>Setting up Apache as SRW/SRU Frontend</title>
+   <example id="server.example.apache.sru"><title>Setting up Apache as SRU Frontend</title>

     <para>
     <para>

-     If you use <ulink url="http://httpd.apache.org/">Apache</ulink>
+     If you use <ulink url="&url.apache;">Apache</ulink>

      as your public web server and want to offer HTTP port 80
      access to the YAZ server on 210, you can use the
      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="http://httpd.apache.org/docs/mod/mod_proxy.html#proxypass">
+     <ulink url="&url.apache.directive.proxypass;">

       <literal>ProxyPass</literal></ulink> 
      directive.
      If you have virtual host
       <literal>ProxyPass</literal></ulink> 
      directive.
      If you have virtual host

@@ -810,14 +809,15 @@ typedef struct bend_scan_rr {
        ErrorLog /home/srw/logs/error_log
        TransferLog /home/srw/logs/access_log
        ProxyPass / http://srw.mydomain:210/
        ErrorLog /home/srw/logs/error_log
        TransferLog /home/srw/logs/access_log
        ProxyPass / http://srw.mydomain:210/

-      &lt;/VirualHost>
+      &lt;/VirtualHost>

      </screen>
     </para>
     <para>
      The above for the Apache 1.3 series.
     </para>
    </example>
      </screen>
     </para>
     <para>
      The above for the Apache 1.3 series.
     </para>
    </example>

-   <example><title>Running a aerver with local access only</title>
+   <example id="server.example.local.access">
+    <title>Running a server with local access only</title>

     <para>
      Servers that is only being accessed from the local host should listen
      on UNIX file socket rather than a Internet socket. To listen on
     <para>
      Servers that is only being accessed from the local host should listen
      on UNIX file socket rather than a Internet socket. To listen on

@@ -828,6 +828,9 @@ typedef struct bend_scan_rr {
     </para>
    </example>
   </sect1>
     </para>
    </example>
   </sect1>

+  <sect1 id="server.vhosts"><title>Virtual Hosts</title>
+   &gfs-virtual;
+  </sect1>

  </chapter>
  
  <!-- Keep this comment at the end of the file
  </chapter>
  
  <!-- Keep this comment at the end of the file