-<!-- $Id: frontend.xml,v 1.22 2004-03-19 21:12:13 adam Exp $ -->
+<!-- $Id: frontend.xml,v 1.33 2007-02-01 09:56:14 adam Exp $ -->
<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 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.
Result-Set Sort (optional).
</para></listitem>
+ <listitem><para>
+ Return Explain for SRU (optional).
+ </para></listitem>
+
</itemizedlist>
<para>
</para>
<synopsis>
-statserv_options_block *statserv_getcontrol(void);
+ statserv_options_block *statserv_getcontrol(void);
</synopsis>
<para>
</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[ODR_MAXNAME+1]</literal></term>
+ <literal>char logfile[ODR_MAXNAME+1]</literal></term>
<listitem><para>File for diagnostic output ("": stderr).
</para></listitem></varlistentry>
<varlistentry><term>
- <literal>char apdufile[ODR_MAXNAME+1]</literal></term>
+ <literal>char apdufile[ODR_MAXNAME+1]</literal></term>
<listitem><para>
Name of file for logging incoming and outgoing APDUs
("": don't log APDUs, "-":
</para></listitem></varlistentry>
<varlistentry><term>
- <literal>char default_listen[1024]</literal></term>
+ <literal>char default_listen[1024]</literal></term>
<listitem><para>Same form as the command-line specification of
listener address. "": no default listener address.
Default is to listen at "tcp:@:9999". You can only
<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>
- <literal>char configname[ODR_MAXNAME+1]</literal></term>
+ <literal>char configname[ODR_MAXNAME+1]</literal></term>
<listitem><para>Passed to the backend when a new connection is received.
</para></listitem></varlistentry>
<varlistentry><term>
- <literal>char setuid[ODR_MAXNAME+1]</literal></term>
+ <literal>char setuid[ODR_MAXNAME+1]</literal></term>
<listitem><para>Set user id to the user specified, after binding
the listener addresses.
</para></listitem></varlistentry>
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);
</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>
/* 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
</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
int hits; /* number of hits */
int errcode; /* 0==OK */
char *errstring; /* system error string or NULL */
+ Z_OtherInformation *search_info;
} bend_search_rr;
</synopsis>
<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
- <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.
- 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>
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
</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 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>
</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
</sect2>
- <sect2><title>scan</title>
+ <sect2 id="server.scan"><title>Scan</title>
<para>
For servers that wish to offer the scan service one handler
bend_scan_status status;
int errcode;
char *errstring;
+ char *scanClause; /* CQL scan clause */
} 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>
The finished application has the following
invocation syntax (by way of <function>statserv_main()</function>):
</para>
-
- <cmdsynopsis>
- <command>appname</command>
- <arg choice="opt"><option>-install</option></arg>
- <arg choice="opt"><option>-installa</option></arg>
- <arg choice="opt"><option>-remove</option></arg>
- <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>-p <replaceable>pidfile</replaceable></option></arg>
- <arg choice="opt"><option>-ziDST1</option></arg>
- <arg choice="opt" rep="repeat">listener-spec</arg>
- </cmdsynopsis>
+
+ &gfs-synopsis;
<para>
The options are:
- &ztest-options;
+ &gfs-options;
</para>
</para>
<synopsis>
- hostname | IP-number [: portnumber]
+ hostname | IP-number [: portnumber]
</synopsis>
<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.
</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>
- <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>
- 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
- <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
ErrorLog /home/srw/logs/error_log
TransferLog /home/srw/logs/access_log
ProxyPass / http://srw.mydomain:210/
- </VirualHost>
+ </VirtualHost>
</screen>
</para>
<para>
The above for the Apache 1.3 series.
</para>
</example>
- <example><title>Running a server 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>
</example>
</sect1>
+ <sect1 id="server.vhosts"><title>Virtual Hosts</title>
+ &gfs-virtual;
+ </sect1>
</chapter>
<!-- Keep this comment at the end of the file
projects / yaz-moved-to-github.git / blobdiff